From 887179ec9fae00c0bcb58eba9bc325668c68751c Mon Sep 17 00:00:00 2001 From: Yentl Van Tendeloo Date: Wed, 11 Jul 2018 17:22:44 +0200 Subject: [PATCH] Add initial description of tracers and link to core documentation --- doc/advanced.rst | 1 + doc/tracers_all.rst | 159 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 doc/tracers_all.rst diff --git a/doc/advanced.rst b/doc/advanced.rst index fa302b5..44e11cb 100644 --- a/doc/advanced.rst +++ b/doc/advanced.rst @@ -22,6 +22,7 @@ In this section, we will continue using the model from the previous section wher .. toctree:: :maxdepth: 1 + Tracers Reinitialisation Continuing a simulation Minimal simulation kernel diff --git a/doc/tracers_all.rst b/doc/tracers_all.rst new file mode 100644 index 0000000..3e96c39 --- /dev/null +++ b/doc/tracers_all.rst @@ -0,0 +1,159 @@ +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.