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 15 and Line 21), 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 the same name, and its path used as required argument for SimulatorToFMU.py.