Tracers ======= PythonPDEVS provides several features that allow you to trace the execution of your model. Here, we present four built-in tracers, and present the interface used to create your own tracer. For all tracers, providing the *None* object as the filename causes the trace to be printed to stdout, instead of writing it to a file. In the context of distributed simulation, tracing is a *destructive event*, meaning that it can only occur after the GVT. As such, tracing happens in blocks as soon as fossil collection occurs. Verbose ------- The first tracer is the verbose tracer, which generates a purely textual trace of your model execution. It has already been presented before, and was used by invoking the following configuration option:: sim.setVerbose(None) Note that this is the only built-in tracer that works without additional configuration of the model. An example snippet is shown below:: __ Current Time: 0.00 __________________________________________ INITIAL CONDITIONS in model Initial State: red Next scheduled internal transition at time 58.50 INITIAL CONDITIONS in model Initial State: idle Next scheduled internal transition at time 200.00 __ Current Time: 58.50 __________________________________________ INTERNAL TRANSITION in model New State: green Output Port Configuration: port : grey Next scheduled internal transition at time 108.50 __ Current Time: 108.50 __________________________________________ INTERNAL TRANSITION in model New State: yellow Output Port Configuration: port : yellow Next scheduled internal transition at time 118.50 ... __ Current Time: 200.00 __________________________________________ EXTERNAL TRANSITION in model Input Port Configuration: port : toManual New State: manual Next scheduled internal transition at time inf INTERNAL TRANSITION in model New State: working Output Port Configuration: port : toManual Next scheduled internal transition at time 300.00 XML --- The second tracer is the XML tracer, which generates an XML-structured trace of your model execution, compliant to the notation presented in `Bill Song's thesis `_. It can also simply be enabled by setting the following configuration option:: sim.setXML(None) To enable this XML tracing, the model has to be augmented with facilities to dump the current state in the form of an XML notation. This is done with the *toXML()* method, which has to be defined for all complex states, and must return a string to be embedded in the XML. This string is pasted as-is in the trace file, and should therefore not contain forbidden characters (e.g., <). For example, a *toXML* method for the traffic light can look as follows:: class TrafficLightMode: ... def toXML(self): return "%s" % self.__colour An example snippet is shown below:: trafficSystem.trafficLight EX red trafficSystem.policeman EX idle trafficSystem.trafficLight IN grey green ... trafficSystem.policeman IN toManual working trafficSystem.trafficLight EX toManual manual VCD --- TODO Cell ---- The cell tracer is discussed separately, as it has very specific behaviour and is only applicable to a select number of models. Custom ------ Additionally, it might necessary to define your own custom tracer. This can be done by defining a class similar to the following template. For each trace method, an *aDEVS* parameter is passed, being a reference to the atomic DEVS model doing the transition. On this *aDEVS* object, the following functions and attributes can be accessed: - *aDEVS.getModelFullName()*: full hierarchical name of the model - *aDEVS.IPorts*: reference to all input ports - *aDEVS.OPorts*: reference to all output ports - *aDEVS.state*: state of model - *aDEVS.time_last[0]*: Time of next transition - *aDEVS.time_next[0]*: Time of next transition - *aDEVS.my_output*: dictionary of output events - *aDEVS.my_input*: dictionary of input events - *aDEVS.elapsed*: elapsed time before transition A custom tracer can be defined as follows:: class TracerCustom(object): def __init__(self, uid, server, filename): """ Both uid and server can be ignored, as these are only required for distributed simulation filename contains the name of the file in which we should write the trace """ pass def startTracer(self, recover): """ Recover is a boolean representing whether or not this is a recovered call (e.g., should the file be overwritten or appended to?) """ pass def stopTracer(self): """ Stops the tracer (e.g., flush the file) """ pass def traceInternal(self, aDEVS): """ Called for each atomic DEVS model that does an internal transition. """ pass def traceExternal(self, aDEVS): """ Called for each atomic DEVS model that does an external transition. """ pass def traceConfluent(self, aDEVS): """ Called for each atomic DEVS model that does a confluent transition. """ pass def traceInit(self, aDEVS, t): """ Called upon initialization of a model. The parameter *t* contains the time at which the model commences (likely 0). """ pass def traceUser(self, time, aDEVS, variable, value): """ Called upon so called *god events* during debuggin, where a user manually alters the state of an atomic DEVS instance. """ pass For some "example" tracers, have a look at the built-in tracers of PythonPDEVS, which can be found in *src/tracers*. Note that in optimistic synchronization the destructive parts of this operation should be separated. This can be done using the *runTraceAtController* function:: runTraceAtController(server, uid, aDEVS, [time, trace_text]) Both the *server* and *uid* are those passed to the constructor of the tracer. Finally, after the tracer is defined, it needs to be registered for the simulator to use it. This is done using the following call on the instantiated simulator:: sim.setCustomTracer(self, tracerfile, tracerclass, args): Where: - *tracerfile*: the Python class containing the implementation of the tracer, which is dynamically imported. - *tracerclass*: the name of the class implementing the tracing functionality. - *args*: the list of arguments that must additionally be passed to the tracer (e.g., filename)