5.2. Ptolemy II

5.2. Ptolemy II
	Chapter 5. Configuring programs for use with the BCVTB

For Ptolemy II related information, we recommend to read the Ptolemy II web page and the Ptolemy II tutorial from UC Berkeley.

5.2.1. Synchronous Data Flow (SDF) director

In Ptolemy II, different models of computations can be used to define how the different actors interact with each other. The model of computation is defined by a director that needs to be included in the Ptolemy II flow chart diagram. For the BCVTB, we typically use the Synchronous Dataflow director, which is in Ptolemy II called SDF Director. This director can be dragged into the model from the left pane shown in Figure 5.1 .

Figure 5.1. Ptolemy II system model that connects a model of a controller and a room.

For convenience, the examples in the BCVTB expose the three parameters beginTime, timeStep and endTime. These three parameters have units of seconds and needs to correspond with the begin time, time step and end time that is used in the simulation program. The parameters used to configure the SDF Director are shown in Figure 5.2 .

Figure 5.2. Configuration of the SDF director.

Flow charts with the SDF director must not contain algebraic loops. If there is an algebraic loop, then a sample delay actor needs to be inserted. This actor can be found in the Ptolemy II actor library in (Actors->FlowControl->SequenceControl->SampleDelay). Figure 5.3 shows the use of a SampleDelay actor for delaying the output of a controller by one sampling interval.

Figure 5.3. Implementation of the controller with the SampleDelay actor that delays its output by one sampling interval. This delay eliminates an algebraic loop, which is not allowed with the SDF director.

Implementation of the controller with the SampleDelay actor that delays its output by one sampling interval. This delay eliminates an algebraic loop, which is not allowed with the SDF director.

The Simulator actor conducts the data exchange with the simulation program. There can be any number of Simulator actors in a model. The parameters of the Simulator actor are as shown in Table 5.1, “Parameters of the Simulator actor.” .

Table 5.1. Parameters of the Simulator actor.

Parameter	Description
programName	The name of the executable that starts the simulation.
programArguments	Arguments needed by the simulation. Text arguments need to be enclosed in apostrophes.
workingDirectory	Working directory of the program. For the current directory, enter a period.
simulationLogFile	Name of the file to which the BCVTB will write the console output and error stream that it receives from the simulation program. Use a separate file for each simulation program. This file typically shows what may have caused an error.
socketTimeout	Time out in milliseconds for the initial socket connection. At the start of the simulation, the BCVTB waits for the simulation program to connect through a socket connection to the BCVTB. If the simulation program does not connect within the here specified time, the BCVTB will stop with an error.
showConsoleWindow	Check box; if activated, a separate window will be opened that displays the console output of the program.

	Note
	The value of the parameter `workingDirectory` needs to be unique. If multiple `Simulator` actors are used, then each `Simulator` actor needs to have its own working directory. Otherwise, the BCVTB stops with an error message because they would overwrite each other's files.

An example that starts EnergyPlus on Linux and Mac is shown in Figure 5.4 .

Figure 5.4. Configuration of the Simulator actor that starts EnergyPlus on Linux.

Note

In EnergyPlus 8.3.0 and higher, a cross platform's command line interface called energyplus was added to EnergyPlus to run it from the command line. Figure 5.5 shows how the Simulator actor uses this interface to call Energyplus. The actor calls the program energyplus with a list of parameters which are required to launch and execute EnergyPlus. Details about the interface can be found at https://github.com/NREL/EnergyPlus/blob/develop/doc/running-energyplus-from-command-line.md.

Figure 5.5. Configuration of the Simulator actor that uses the command line interface to call EnergyPlus.

5.2.2. Data Type Conversion

Figure 5.6. Ptolemy II system model that converts an array of strings into an array of doubles.

This example shows how to convert an array of strings into an array of doubles in Ptolemy II. Such a type conversion may be needed if the output of the BACnetReader actor is used by other actors. The model shown in Figure 5.6 illustrates the type conversion and can be found in the directory bcvtb/examples/ptolemy-dataTypeConversion. The conversion was done by

dragging and dropping an IterateOverArray actor from the library,
dragging an ExpressionToToken actor from the library onto it (See Figure 5.7),
setting the output of the IterateOverArray actor to arrayType(double) by right clicking on IterateOverArray and selecting Customize->Ports,
including an additional ExpressionToToken actor to the system model where its output is connected to the IterateOverArray actor input,
setting the output of the ExpressionToToken actor to arrayType(string),
adding an arrayToMatrix actor to the system model and setting the output of this actor to [double].

Figure 5.7. Ptolemy II system model that shows the use of the IterateOverArray actor.


Chapter 5. Configuring programs for use with the BCVTB		5.3. EnergyPlus