3. Best Practice¶
This section explains to users the best practice in configuring a Simulator XML input file, and implementing the Python wrapper which will interface with the Simulator.
3.1. Configuring the Simulator XML input file¶
To export a Simulator as an FMU, the user needs to write an XML file which contains the list
of inputs, outputs and parameters of the FMU. The XML snippet below shows how a user has to write such an input file.
A template named SimulatorModeldescritpion.xml
which shows such a file is provided in the parser/utilities
installation folder of SimulatorToFMU.
This template should be adapted to create new XML input file.
The following snippet shows an input file where the user defines 1 input and 1 output variable.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | <?xml version="1.0" encoding="UTF-8"?>
<SimulatorModelDescription
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
fmiVersion="2.0"
modelName="simulator"
description="Input data for a Simulator FMU"
generationTool="SimulatorToFMU">
<ModelVariables>
<ScalarVariable
name="v"
description="Voltage"
causality="input">
<Real
unit="V"
start="0.0"/>
</ScalarVariable>
<ScalarVariable
name="i"
description="Current"
causality="output">
<Real
unit="A"/>
</ScalarVariable>
</ModelVariables>
</SimulatorModelDescription>
|
To create such an input file, the user needs to specify the name of the FMU (Line 5).
This is the modelName
which should be unique.
The user then needs to define the inputs and outputs of the FMUs.
This is done by adding a ScalarVariable
into the list of ModelVariables
.
To parametrize the ScalarVariable
as an input variable, the user needs to
- define the name of the variable (Line 10),
- give a brief description of the variable (Line 11)
- give the causality of the variable (
input
for inputs,output
for outputs) (Line 12)- define the type of variable (Currently only
Real
variables are supported) (Line 13)- give the unit of the variable (Currently only valid Modelica units are supported) (Line 14)
- give a start value for the input variable (This is optional) (Line 15)
To parametrize the ScalarVariable
as an output variable, the user needs to
- define the name of the variable (Line 18),
- give a brief description of the variable (Line 19)
- give the causality of the variable (
input
for inputs,output
for outputs) (Line 20)- define the type of variable (Currently only
Real
variables are supported) (Line 21)- give the unit of the variable (Currently only valid Modelica units are supported) (Line 22)
Note
If valid Modelica units can’t be used (Line 14 and Line 22), then remove the unit field from the input file
when defining new ScalarVariable
.
3.2. Configuring the Python Wrapper Simulator¶
To export Simulator as an FMU, the user needs to write the Python wrapper which will interface with the Simulator. The wrapper will be embedded in the FMU when the Simulator is exported and used at runtime on the target machine.
The user needs to extend the Python wrapper provided in parser/utilities/simulator_wrapper.py
and implements the function exchange
.
The following snippet shows the Simulator function.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | # Main Python function to be modified to interface with the main simulator.
def exchange(configuration_file, time, input_names,
input_values, output_names, write_results):
"""
Return a list of output values from the Python-based Simulator.
The order of the output values must match the order of the output names.
:param configuration_file (String): Path to the Simulator model or configuration file
:param time (Float): Simulation time
:param input_names (Strings): Input names
:param input_values (Floats): Input values (same length as input_names)
:param output_names (Strings): Output names
:param write_results (Float): Store results to file (1 to store, 0 else)
Example:
>>> configuration_file = 'config.json'
>>> time = 0
>>> input_names = 'v'
>>> input_values = 220.0
>>> output_names = 'i'
>>> write_results = 0
>>> output_values = simulator(configuration_file, time, input_names,
input_values, output_names, write_results)
"""
#######################################################################
# EDIT AND INCLUDE CUSTOM CODE FOR TARGET SIMULATOR
# Include body of the function used to compute the output values
# based on the inputs received by the simulator function.
# This function currently returns dummy output values.
# This will need to be adapted so it returns the correct output_values.
# If the list of output names has only one name, then only a scalar
# must be returned.
if (len(output_names) > 1):
output_values = [1.0] * len(output_names)
else:
output_values = 1.0
#########################################################################
return output_values
|
The arguments of the functions are in the next table
Arguments | Description |
---|---|
configuration_file |
The Path to the Simulator model or configuration file |
time |
The current simulation model time |
input_names |
The list of input names of the FMU |
input_values |
The list of input values of the FMU |
output_names |
The list of output names of the FMU |
output_values |
The list of output values of the FMU |
write_results |
A flag for writing results to a file |
Note
- The function
exchange
must return a list of output values which matches the order of the output names. - The function
exchange
can be used to invoke external programs/scripts which do not ship with the FMU. The external programs/scripts will have to be installed on the target machine where the FMU is run. See Creating an FMU for details on command line options. - Once
simulator_wrapper.py
is implemented, it must be saved under a name of the form"modelname"
+"_wrapper.py"
, and its path used as required argument forSimulatorToFMU.py
.