Creating custom simulations with Python API

Warning

Depending on your hardware, and simulation setup, creating datasets with BeRfiPl simulation models may take some time.

When using the Python API a structural manipulation of the CPS modules is not possible. Mainly the composition of the Cyber-Physical Process Plant and its high level parametrization is manipulable. You can adapt the existing simulation setups or introduce your own setups in three steps:

Step 1:

To manipulate the Cyber-Physical Process Plant setup the benchmark_config.json must be changed. It is important to fill out all points in the config file, otherwise the simulation can be corrupted. Below is a sample simulation setup:

 1{
 2   "ds1": {
 3      "model": {
 4         "nodes": ["mixer_partial0", "source0", "source1", "source2", "sink0"],
 5         "edges": [["source0", "mixer_partial0"], ["source1", "mixer_partial0"], ["source2", "mixer_partial0"], ["mixer_partial0", "sink0"]]},
 6      "faults": ["l", "c", "lc"],
 7      "faulty_module": ["mixer_partial0"],
 8      "ProdIn": ["red", "yellow", "blue"],
 9      "ProdOut": ["redyellowblue"],
10      "startTime": 0,
11      "stopTime": 4000,
12      "numberOfIntervals": 40000,
13      "errorInduction": 2000
14      }
15}
The config file contains a dictionary, which includes:
  • The dataset name

    In this case ds1. The name can be customized.

  • The configuration

    The configuration of the Cyber-Physical Process Plants is noted in the form of a directed graph under model. Under nodes all employed modules in the custom setup have to be listed as strings. Under edges the directed connections between the employed modules have to be listed as tuples in list form.

    Important: Every input and output of a module must be connected. If there is no preceding or succeeding module, place a source or sink, respectively.

    Important: The modules have to be indexed! Modules without an index will cause errors in the compilation of the simulation.

  • The Faults

    Under faults one of three employable faults can be added to the simulation. Each element in the list will create a new dataset, which will contain the employed fault. If "" is added to the list, a fault-free dataset will be generated. The fault cases are:

    • "" : no faults.

    • "l" : a leakage will be induced. The leakage will purge some of the volume flow into a sink outside the system

    • "c" : a clogging will be induced. The clogging will reduce the diameter of a pipe within a module and lead to an increase in pressure.

    • "lc" : a leakage and a clogging will be induced. The named effects will be included superposed within the dataset.

  • The faulty module

    Under faulty_module the faulty module can be selected. The name must match a module name (with index!) from the model:nodes list.

  • Input products & output products

    Under ProdIn and ProdOut a list of the input products and output products of the Cyber-Physical Process Plant is given. The names of the products can be customized. We suggest colors red, yellow, and blue. Additionally, adjectives, like *_bottled, *_distilled, or proportions like *_0.8 can be added. Optionally, product descriptions in any variety can be added. This feature mainly focuses on the planning aspect of the dataset.

  • Simulation start time
    startTime is ndicating the time from which the simulation is going to generate data.

    (Standard value: 0)

  • Simulation stop time
    stopTime is indicating the time the simulation will be stopped.

    (Standard value: 4000)

  • Number of intervals
    numberOfIntervalls is indicating the number of intervals that will be simulated, or indirectly the sampling rate.

    (Standard value: 40000)

  • Fault induction

    Under errorInduction the time your error will be induced can be chosen.

    The time must always be smaller than your simulation stop time.

Once you adapted the config file, save it under benchmark_config.json in JSON format.

Step 2:

After adapting your Cyber-Physical Process Plant setup you can customize your simulation setup and its hyper-parameters. Therefore you can either change call.mos file or add the simulation hyper-parameters in your config.json file. This file executes the modelica simulation. Especially the last line of this file is of interest. The preceding lines are for importing all models. In case you did not add any additional modules, they are not in your interest. If you want to change the call.mos manually change this:

simulate(process_plant, startTime = 0, stopTime=4000, numberOfIntervals=40000, outputFormat="csv", simflags="-maxIntegrationOrder=1");
Within the last lines you can set the simulation hyperparameters like:
  • startTime

    Indicating the time from which the simulation is going to generate data. (Standard value: 0)

  • stopTime

    Indicating the time the simulation will be stopped. (Standard value: 4000)

  • numberOfIntervalls

    Indicating the number of intervals that will be simulated, or indirectly the sampling rate. (Standard value: 40000)

  • outputFormat

    Format of output file (standard value: “csv”)

Step 3:

Once you adapted your simulation hyper-parameters, you can now run the create_benchmark.py file in your terminal. The datasets will be saved to the ./datasets directory. To run create_benchmark.py navigate to the repository in your terminal, activate your conda environment and type:

(berfiple) $ python create_benchmark.py

To understand on how the create_benchmark.py script is running the simulation, please visit its entry.

Note

In case the simulation does not work, you probably did something wrong in the preceding steps. Review your steps rigorously and run the simulation again.