org.hlacerti.lib

Class HlaManager

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.AbstractInitializableAttribute

org.hlacerti.lib.HlaManager

All Implemented Interfaces:

java.lang.Cloneable, Initializable, TimeRegulator, Changeable, Debuggable, DebugListener, Derivable, HierarchyListener, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class HlaManager
extends AbstractInitializableAttribute
implements TimeRegulator

This class implements a HLA Manager which allows a Ptolemy model to cooperate with a HLA/CERTI Federation. The main goal is to allow a Ptolemy simulation as Federate of a Federation.

The High Level Architecture (HLA) [1][2] is a standard for distributed discrete-event simulation. A complex simulation in HLA is called a HLA Federation. A Federation is a collection of Federates (e.g. simpler simulators), each performing a sequence of computations, interconnected by a Run Time Infrastructure (RTI).

CERTI is an Open-Source middleware RTI compliant with HLA [NRS09] which manages every part of federation. It also ensures a real-time behavior of a federation execution. CERTI is implemented in C++ and bindings are provided as JCERTI for Java and PyHLA for Python. For more information see: http://savannah.nongnu.org/projects/certi

The HlaManager attribute handles the time synchronization between Ptolemy model time and HLA logical time by implementing the TimeRegulator interface. It also manages objects that implement interfaces provided by JCERTI relatives to Federation, Declaration, Object and Time management areas in HLA (each management areas provides a set of services).

To develop a HLA Federation it is required to specify a Federate Object Model (FOM) which describes the architecture of the Federation (HLA version, name of Federates which belong to, shared HLA attributes) and the interaction between Federates and shared attributes. Data exchanged in a HLA Federation are called HLA attributes and their interaction mechanism is based on the publish/subscribe paradigm. The FOM is specified in a .fed file used by the RTI (e.g. by the RTIG process when using CERTI). More information in [3].

http://savannah.nongnu.org/projects/certi

To enable a Ptolemy model as a Federate, the HlaManager has to be deployed and configured (by double-clicking on the attribute). Parameters federateName, federationName have to match the declaration in the FOM (.fed file). fedFile specifies the FOM file and its path.

Parameters useNextEventRequest, UseTimeAdvanceRequest, isTimeConstrained and isTimeRegulator are used to configure the HLA time management services of the Federate. A Federate can only specify the use of the nextEventRequest() service or the timeAdvanceRequest() service at a time. istimeConstrained is used to specify time-constrained Federate and istimeRegulator to specify time-regulator Federate. The combination of both parameters is possible and is recommended.

Parameters, hlaStepTime and hlaLookAHead are used to specify Hla Timing attributes of a Federate.

Parameters requireSynchronization, synchronizationPointName and isCreatorSyncPt are used to configure HLA synchronization point. This mechanism is usually used to synchronize the Federates, during their initialization, to avoid that Federates that only consume some HLA attributes finished their simulation before the other federates have started. isCreatorSyncPt indicates if the Federate is the creator of the synchronization. Only one Federate can create the named synchronization point for the whole HLA Federation.

HlaPublisher and HlaSubscriber actors are used to respectively publish and subscribe to HLA attributes. The name of those actors and their classObjectHandle parameter have to match the identifier of the shared HLA attributes and their object class that they belong to, specified in the FOM (.fed file).

For a correct execution, the CERTI_HOME environment variable has to be set. It could be set in the shell (by running one of the scripts provided by CERTI) where Vergil is executed, or as a parameter of the Ptolemy model or as a parameter of the HlaManager:

 CERTI_HOME="/absolute/path/to/certi/"
 

Otherwise, the current implementation is not able to find the CERTI environment, the RTIG binary and to perform its execution. See also the CertiRtig class.

NOTE: For a correct behavior CERTI has to be compiled with the option "CERTI_USE_NULL_PRIME_MESSAGE_PROTOCOL"

References:

[1] Dpt. of Defense (DoD) Specifications, "High Level Architecture Interface Specification, Version 1.3", DOD/DMSO HLA IF 1.3, Tech. Rep., Apr 1998.

[2] IEEE, "IEEE standard for modeling and simulation High Level Architecture (HLA)", IEEE Std 1516-2010, vol. 18, pp. 1-38, 2010.

[3] D. of Defense (DoD) Specifications, "High Level Architecture Object Model Template, Version 1.3", DOD/DMSO OMT 1.3, Tech. Rep., Feb 1998.

[4] E. Noulard, J.-Y. Rousselot, and P. Siron, "CERTI, an open source RTI, why and how ?", Spring Simulation Interoperability Workshop, pp. 23-27, Mar 2009.

[5] Y. Li, J. Cardoso, and P. Siron, "A distributed Simulation Environment for Cyber-Physical Systems", Sept 2015.

[6] J. Cardoso, and P. Siron, "Ptolemy-HLA: a Cyber-Physical System Distributed Simulation Framework", Festschrift Lee, Internal DISC report, 2017.

Since:

Ptolemy II 11.0

Version:

$Id: HlaManager.java 214 2018-04-01 13:32:02Z j.cardoso $

Author:

Gilles Lasnier, Contributors: Patricia Derler, Edward A. Lee, David Come, Yanxuan LI

Pt.AcceptedRating:

Red (glasnier)

Pt.ProposedRating:

Yellow (glasnier)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	HlaManager.ETimeManagementService Enumeration which represents both time advancement services NER or TAR.

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.HashMap<java.lang.String,java.util.LinkedList<TimedEvent>>	_fromFederationEvents List of events received from the HLA/CERTI Federation and indexed by the HlaSubscriber actors present in the model.
protected java.util.HashMap<java.lang.String,java.lang.Object[]>	_hlaAttributesToPublish Table of HLA attributes (and their HLA information) that are published by the current HlaManager to the HLA/CERTI Federation.
protected java.util.HashMap<java.lang.String,java.lang.Object[]>	_hlaAttributesToSubscribeTo Table of HLA attributes (and their HLA information) that the current HlaManager is subscribed to.
protected java.util.HashMap<java.lang.Integer,java.lang.Integer>	_objectIdToClassHandle Table of object class handles associate to object ids received by discoverObjectInstance and reflectAttributesValues services (e.g. from the RTI).
protected java.util.HashMap<java.lang.String,java.lang.Boolean>	_usedJokerFilterMap Table of used joker (wildcard) filter.
Parameter	enableHlaReporter Boolean value, 'true' if the generation of HLA reports is enabled 'false' if not.
Parameter	federateName Name of the Ptolemy Federate.
Parameter	federationName Name of the federation.
FileParameter	fedFile Path and name of the Federate Object Model (FOM) file.
Parameter	hlaLookAHead Value of the lookahead of the HLA ptII federate.
FileParameter	hlaReportPath Path and name of the HLA folder to store reports.
Parameter	hlaTimeStep Value of the time step of the Federate.
Parameter	hlaTimeUnit Double value for representing how much is a unit of time in the simulation.
Parameter	isCreator Boolean value, 'true' if the Federate is the creator of the synchronization point 'false' if not.
Parameter	isTimeConstrained Boolean value, 'true' if the Federate is declared time constrained 'false' if not.
Parameter	isTimeRegulator Boolean value, 'true' if the Federate is declared time regulator 'false' if not.
Parameter	requireSynchronization Boolean value, 'true' if the Federate is synchronised with other Federates using a HLA synchronization point, 'false' if not.
Parameter	synchronizationPointName Name of the synchronization point (if required).
ChoiceParameter	timeManagementService Choice of time advancement service (NER or exclusive TAR).

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
HlaManager(CompositeEntity container, java.lang.String name) Construct a HlaManager with a name and a container.

Method Summary

Modifier and Type	Method and Description
void	attributeChanged(Attribute attribute) Checks constraints on the changed attribute (when it is required) and associates his value to its corresponding local variables.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	initialize() Initializes the HlaManager attribute.
boolean	noNewActors() Return always true.
void	preinitialize() Launch the HLA/CERTI RTIG process as subprocess.
Time	proposeTime(Time proposedTime) Propose a time to advance to.
void	updateHlaAttribute(HlaPublisher hp, Token in) Update the HLA attribute attributeName with the containment of the token in.
void	wrapup() Manage the correct termination of the HlaManager.

Methods inherited from class ptolemy.actor.AbstractInitializableAttribute

_getInitializableContainer, addInitializable, hierarchyChanged, hierarchyWillChange, removeInitializable, setContainer

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Field Detail

federateName

public Parameter federateName

Name of the Ptolemy Federate. This parameter must contain an StringToken.

federationName

public Parameter federationName

Name of the federation. This parameter must contain an StringToken.

fedFile

public FileParameter fedFile

Path and name of the Federate Object Model (FOM) file. This parameter must contain an StringToken.

hlaTimeUnit

public Parameter hlaTimeUnit

Double value for representing how much is a unit of time in the simulation. Has an impact on TAR/NER/RAV/UAV.

isCreator

public Parameter isCreator

Boolean value, 'true' if the Federate is the creator of the synchronization point 'false' if not. This parameter must contain an BooleanToken.

isTimeConstrained

public Parameter isTimeConstrained

Boolean value, 'true' if the Federate is declared time constrained 'false' if not. This parameter must contain an BooleanToken.

isTimeRegulator

public Parameter isTimeRegulator

Boolean value, 'true' if the Federate is declared time regulator 'false' if not. This parameter must contain an BooleanToken.

hlaTimeStep

public Parameter hlaTimeStep

Value of the time step of the Federate. This parameter must contain an DoubleToken.

hlaLookAHead

public Parameter hlaLookAHead

Value of the lookahead of the HLA ptII federate. This parameter must contain an DoubleToken.

requireSynchronization

public Parameter requireSynchronization

Boolean value, 'true' if the Federate is synchronised with other Federates using a HLA synchronization point, 'false' if not. This parameter must contain an BooleanToken.

synchronizationPointName

public Parameter synchronizationPointName

Name of the synchronization point (if required). This parameter must contain an StringToken.

timeManagementService

public ChoiceParameter timeManagementService

Choice of time advancement service (NER or exclusive TAR).

enableHlaReporter

public Parameter enableHlaReporter

Boolean value, 'true' if the generation of HLA reports is enabled 'false' if not. This parameter must contain an BooleanToken.

hlaReportPath

public FileParameter hlaReportPath

Path and name of the HLA folder to store reports. This parameter must contain a String.

_hlaAttributesToPublish

protected java.util.HashMap<java.lang.String,java.lang.Object[]> _hlaAttributesToPublish

Table of HLA attributes (and their HLA information) that are published by the current HlaManager to the HLA/CERTI Federation. This table is indexed by the HlaPublisher actors present in the model.

_hlaAttributesToSubscribeTo

protected java.util.HashMap<java.lang.String,java.lang.Object[]> _hlaAttributesToSubscribeTo

Table of HLA attributes (and their HLA information) that the current HlaManager is subscribed to. This table is indexed by the HlaSubscriber actors present in the model.

_fromFederationEvents

protected java.util.HashMap<java.lang.String,java.util.LinkedList<TimedEvent>> _fromFederationEvents

List of events received from the HLA/CERTI Federation and indexed by the HlaSubscriber actors present in the model.

_objectIdToClassHandle

protected java.util.HashMap<java.lang.Integer,java.lang.Integer> _objectIdToClassHandle

Table of object class handles associate to object ids received by discoverObjectInstance and reflectAttributesValues services (e.g. from the RTI).

_usedJokerFilterMap

protected java.util.HashMap<java.lang.String,java.lang.Boolean> _usedJokerFilterMap

Table of used joker (wildcard) filter.

Constructor Detail

HlaManager

public HlaManager(CompositeEntity container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException

Construct a HlaManager with a name and a container. The container argument must not be null, or a NullPointerException will be thrown. This actor will use the workspace of the container for synchronization and version counts. If the name argument is null, then the name is set to the empty string. Increment the version of the workspace.

Parameters:

container - Container of this attribute.

name - Name of this attribute.

Throws:

IllegalActionException - If the container is incompatible with this actor.

NameDuplicationException - If the name coincides with an actor already in the container.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Checks constraints on the changed attribute (when it is required) and associates his value to its corresponding local variables.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the attribute is empty or negative.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace.

Overrides:

clone in class AbstractInitializableAttribute

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

Object.clone()

initialize

public void initialize()
                throws IllegalActionException

Initializes the HlaManager attribute. This method: calls the _populateHlaAttributeTables() to initialize HLA attributes to publish or subscribe to; instantiates and initializes the RTIambassador and FederateAmbassador which handle the communication Federate <-> RTIA <-> RTIG. RTIA and RTIG are both external communicant processes (see JCERTI); create the HLA/CERTI Federation (if not exists); allows the Federate to join the Federation; set the Federate time management policies (regulator and/or contrained); creates a synchronisation point (if required); and synchronizes the Federate with a synchronization point (if declared).

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AbstractInitializableAttribute

Throws:

IllegalActionException - If the container of the class is not an Actor or If a CERTI exception is raised and has to be displayed to the user.

noNewActors

public boolean noNewActors()

Return always true. This function is no more used in this implementation of TimeRegulator interface. It must return true otherwise the proposeTime() will enter in an infinite loop.

Specified by:

noNewActors in interface TimeRegulator

Returns:

true always return true

preinitialize

public void preinitialize()
                   throws IllegalActionException

Launch the HLA/CERTI RTIG process as subprocess. The RTIG has to be launched before the initialization of a Federate. NOTE: if another HlaManager (e.g. Federate) has already launched a RTIG, the subprocess creates here is no longer required, then we destroy it.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AbstractInitializableAttribute

Throws:

IllegalActionException - If the initialization of the CertiRtig or the execution of the RTIG as subprocess has failed.

proposeTime

public Time proposeTime(Time proposedTime)
                 throws IllegalActionException

Propose a time to advance to. This method is the one implementing the TimeRegulator interface and using the HLA/CERTI Time Management services (if required). Following HLA and CERTI recommendations, if the Time Management is required then we have the following behavior: Case 1: If lookahead = 0 -a) if time-stepped Federate, then the timeAdvanceRequestAvailable() (TARA) service is used; -b) if event-based Federate, then the nextEventRequestAvailable() (NERA) service is used Case 2: If lookahead > 0 -c) if time-stepped Federate, then timeAdvanceRequest() (TAR) is used; -d) if event-based Federate, then the nextEventRequest() (NER) is used; Otherwise the proposedTime is returned. NOTE: For the Ptolemy II - HLA/CERTI cooperation the default (and correct) behavior is the case 1 and CERTI has to be compiled with the option "CERTI_USE_NULL_PRIME_MESSAGE_PROTOCOL".

Specified by:

proposeTime in interface TimeRegulator

Parameters:

proposedTime - The proposed time.

Returns:

The proposed time or a smaller time.

Throws:

IllegalActionException - If this attribute is not contained by an Actor.

updateHlaAttribute

public void updateHlaAttribute(HlaPublisher hp,
                               Token in)
                        throws IllegalActionException

Update the HLA attribute attributeName with the containment of the token in. The updated attribute is sent to the HLA/CERTI Federation.

Parameters:

hp - The HLA publisher actor (HLA attribute) to update.

in - The updated value of the HLA attribute to update.

senderName - the name of the federate that sent the attribute.

Throws:

IllegalActionException - If a CERTI exception is raised then displayed it to the user.

wrapup

public void wrapup()
            throws IllegalActionException

Manage the correct termination of the HlaManager. Call the HLA services to: unsubscribe to HLA attributes, unpublish HLA attributes, resign a Federation and destroy a Federation if the current Federate is the last participant.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AbstractInitializableAttribute

Throws:

IllegalActionException - If the parent class throws it of if a CERTI exception is raised then displayed it to the user.