1 Introduction

MBDlyb is an open-source proof-of-concept Python library for the SD2Act project. It allows for experimentation at scale by easily specifying large networks. The library also formalizes and consolidates the research done in the SD2Act project. The high-level overview of the SD2Act methodology as implemented in MBDlyb is shown in the figure below. The orange edges require human involvement while green edges represent fully automated transformations or computations.

2 Installation & usage

This section describes how to install MBDlyb, how to setup the database (Neo4j) which is used to store the models, and how to start MBDlyb.

2.1 Installation

MBDlyb is developed in Python and distributed as a Python wheel package. It is advised to install MBDlyb in a Python virtual environment, e.g., using venv or conda. How to create a virtual environment using venv is described below.

2.1.1 Create a virtual environment

First create a directory for your MBDlyb installation, and open a shell (e.g., Windows PowerShell) in this directory. This can be done using the following commands:

mkdir C:\MBDlyb\
cd C:\MBDlyb\

Run the following command to create a virtual environment using venv named mbdlyb_env:

python -m venv mbdlyb_env

2.1.2 Installing MBDlyb

Open a shell (e.g., Windows PowerShell) in the directory with the virtual environment, and activate the virtual environment:

cd C:\MBDlyb\
.\mbdlyb_env\Scripts\Activate.ps1

The MBDlyb wheel package can be installed using the following command:

pip install <path_to_whl>

This will install MBDlyb, and download and install all its dependencies.

2.2 Setup Neo4j

Neo4j is a graph database management system which is used to store the models used by MBDlyb. It can be downloaded from https://neo4j.com/.

To setup the database for MBDlyb, start Neo4j Desktop and follow these steps:

1. In the Projects pane on the left, create a project by clicking on the New button and selecting Create project.

2. In the pane on the right, add a Database Management System (DBMS) by clicking the Add button and selecting Local DBMS. Give the DBMS an appropriate name by updating the text in the Name field, and specify a password that you will be able to remember.

   For MBDlyb you can specify your own password, however it is recommended to start with the default password.

   In the Version field, select the latest version (5.24.0). Finally click the Create button.

3. Click on the name of the DBMS you just created, which opens a pane with three tabs: Details, Plugins and Upgrade. Select the Plugins tab, select APOC, and click Install.

4. Start the DBMS by clicking on its name and click Start

5. Create a new database by clicking on the DBMS’ name and click Create database. Select a name you prefer, e.g., example-db

After configuring the project, the DBMS and the database Neo4j Desktop should look like this:

2.2.1 Export & import Neo4j databases

Neo4j has the option to dump a database and to import it. This can be used to create a backup, or to share the database with others.

To dump the database follow the following steps:

1. Click the name of the database (e.g., example-db) in the pane on the right
2. Click on the three dots symbol and select Dump

To import a dumped database back into a DBMS follow the following steps:

1. In the pane on the right, click the Add button and select File.
2. Select the database dump file and select Open
3. Click the name of the just opened file and select Import dump into existing DBMS from the menu under the three dots
4. Select the DBMS to import the database into, give the database a name, and select Create

2.3 MBDlyb usage

As a prerequisite, open Neo4j Desktop and start the Database Management System (DBMS):

1. In the Projects pane on the left, select the project.
2. Next select the name of the DBMS and click Start

The interactive model editor and diagnoser can be started from the command line. Open a shell (e.g., Windows PowerShell) in the directory with the virtual environment created for MBDlyb, and activate it:

cd C:\MBDlyb\
.\mbdlyb_env\Scripts\Activate.ps1

MBDlyb can now be started with the following command. Make sure the database name in the --database argument matches the database created in the previous step.

python -m mbdlyb --database=example-db

Note that this command uses the default hostname, port, protocol, username and password. These can also be specified using the arguments --host, --port, --protocol, --username and --password.

Next open a webbrowser and go to http://localhost:8080/. This will open the model editor main page in which you can either open an existing model, create a new model or import an Excel/Json or Capella model.

To get a list of all command line parameters, and instructions on how to use them, run the following command:

python -m mbdlyb --help

3 Modelling

As a demonstration of how to model a system in MBDlyb, this section describes the creation of a simple model of a CD-radio-player.

3.1 Create CD-radio-player model

To start, create a new model in MBDlyb and add the two main functions of the CD-radio-player: PlayCD and PlayRadio.

3.2 CD reader & radio receiver

Next, add a cluster to model the CD reader called CDReader. Its main function is called ReadCD, which is a sub-function of the overall main function PlayCD. The CDReader cluster also contains a hardware node, a diagnostic test node and a test result node.

Also add a cluster to model the radio receiver. This cluster is called RadioReceiver and has a layout similar to the CDReader cluster.

The final CDReader and RadioReceiver clusters look as follows:

3.3 Audio system

The audio system cluster named AudioSystem is very similar to the CD reader and radio receiver clusters. Its main function GenerateAudio is a subfunction of the main functions PlayCD and PlayRadio. The audio system cluster looks as follows:

3.4 Power system

The power system will provide power to all parts of the system. The power source can either be a battery or wall power. The power board in the power system is responsible for selecting one of these sources and distributing the power.

As a first step create the PowerSystem cluster in the CDRadioPlayer main cluster. The main function ProvidePower in the PowerSystem cluster has a direct observable PowerLED which indicates if the power is Ok or not.

3.4.1 Power board

The first cluster in the power system is the PowerBoard. Its main function DistributePower is a sub-function of the PowerSystem cluster’s function ProvidePower. The DistributePower function is required for the ReadCD, ReceiveRadio and GenerateAudio functions. These dependencies are added as required-for relations.

The final PowerBoard cluster looks as follows. Note that the required-for relations from the DistributePower function to the ReadCD, ReceiveRadio and GenerateAudio functions are not shown in this figure.

3.4.2 Operating mode: select power

The CD-radio-player can operate either on battery power or on wall power. This is modelled with an operating mode. An operating mode selector called Select_Power is added to the PowerSystem cluster, which will enable the DistributePower function to choose between battery power and wall power. The two operating modes are called BatteryPower and WallPower.

3.4.3 Battery, AC-DC converter and power cable

The battery, AC-DC converter and power cable are components which are required to provide either battery power or wall power to the power distribution board. This is modelled via required-for relations from the SupplyBatteryPower function in the Battery cluster and from the ConvertACtoDC function in the ACDCConverter cluster to the DistributePower function in the PowerBoard cluster. Which part is active for which power source is modeled using an operating mode BatteryPower or WallPower on these two required-for relations. The SupplyWallPower function in the PowerCable cluster has a required-for relation to the ConvertACtoDC function in the ACDCConverter cluster. The diagnostic tests of these three components test the hardware instead of the function.

The video below demonstrates the modelling of the Battery cluster:

The ACDCConverter and PowerCable clusters are modelled similarly.

The final Battery, ACDCConverter and PowerCable clusters are modelled as follows:

Combining all the components described in the section above, the complete PowerSystem cluster looks as follows:

Note that this overview does not include the operating mode selector Select_Power. Also required-for relations are not shown in this overview. Required-for relations can be viewed using View required-for table. A complete model can be inspected using yEd.

4 Features

This section describes some of the other features in MBDlyb which can be used to e.g. import or check a model.

4.1 View table

The required-for relations of a cluster can be visualized in a table using the “View table” button:

An example table of the required-for relations of the CD-radio-player’s Power system is shown below:

Required-for relations can be added by using the plus-icons. Existing required-for relations can be modified by clicking the edit-pencil on the green background. Function’s can’t have required-for relations to themselves, hence the minus-icons on the diagonal.

4.2 Edit, move and copy

To change the name and the properties of a cluster, function, hardware node, etc., use the edit button to open the edit window:

Clusters can be moved or copied to other clusters using the move- and copy-functions.

4.3 Import

MBDlyb can import models in either the legacy format (Excel + Json) or a Capella model.

To import into an existing model, the import window can be opened with the “Import” button:

To import a new model, navigate to http://localhost:8080/ and open the import window as described in the following sections.

4.3.1 Import Excel model

To import a model in the legacy format (Excel + Json), first open the import window. There specify the main cluster name, upload the Excel file, and, (optionally) the corresponding Json file.

The video below demonstrates importing a CD-radio-player model in the legacy (Excel + Json) format.

4.3.2 Import Capella model

To import a model from Capella, first open the import window. Upload all files which make up the Capella model, and (optionally) select the options to create default tests.

The video below demonstrates importing a CD-radio-player model from Capella.

4.3.2.1 Finetuning a Capella model

When importing models from Capella, the goal is to have the Capella model as complete as possible, so that modifications to the MBDlyb model after Capella import can be kept to a minimum. For this purpose, various elements of the Capella model can be labeled in such a way that they receive a special treatment when importing the model into MBDlyb. For this purpose, the Capella plug-in PVMT needs to be installed. Then the built-in help system of Capella can provide guidance on how to use this plug-in. After importing the file MBDlyb.vpd from the folder capella-extension at the root of this repository, the PVMT editor looks like this:

Now the following action can be taken in the Capella model.

4.3.2.1.1 Labeling a hardware component as inspectable

A logical component in Capella that represents a hardware that can be directly inspected by a service engineer to check whether it is broken or not can be labeled as such by setting the value of the property Inspectable to true. The cost of the inspection can be filled into the Cost property.

When the Capella model is imported into MBDlyb, even if the option Default tests on hardware is off, a test (blue hexagon) with its result (green rectangle) is added for this component:

4.3.2.1.2 Labeling a function as a diagnostic test

A diagnostic test can be defined directly in Capella as follows: * Define a function (in the logical or physical architecture) that represents the test * Set the Diagnostic test property to true and fill in a value for the cost of the test * Define subfunctions of the test and allocate them to the components that are covered by the test. Whenever such subfunctions are basically the same as regular functions of their components, it is a good idea to reflect that in their name. * Several test functions can be grouped as subfunctions of higher-level functions. Whenever such a higher-level function contains only tests, it will not be imported to MBDlyb.

When importing the Capella model into MBDlyb, it is not necessary to choose the option Default tests on functions, since the functions labeled as tests are now shown as such in MBDlyb:

4.3.2.1.3 Labeling a function output as direct observable

When the correct operation of a function is directly observable in the system (e.g., by the presence or absence of an error message), this can be indicated in Capella as follows: * Add an output port to the function and give it a meaningful name * Set the property Observable of the output port to true For each function only one such observable output is meaningful, since it only flags whether the function works correctly.

After import into MBDlyb we see the observable appear:

4.3.2.1.4 Labeling a functional exchange as not required

Sometimes it make sense to have functional exchanges in Capella that display circularity, for example when modeling control loops. This circularity is not allowed in the MBDlyb probabilistic reasoning model, because it would hide underlying hardware malfunctions, and therefore such cycles in the system model are automatically broken when translating them to a reasoning model. Nevertheless it may be useful to have explicit control over breaking the cycles in the Capella model. For this purpose, it is possible to label a functional exchange as not required by setting the Required property to false (note that the default value is true). Typically a good place to do this at the incoming exchange to a function that performs a measurement, since often the value of the measurement is affected by the function before it, but if that preceding function is broken, typically the measurement can still be performed accurately (provided the sensor hardware itself is not broken).

A functional exchange labeled as not required will not be imported into the MBDlyb diagnostic network and therefore it cannot cause a loop. (There is no interesting MBDlyb screenshot to show this). Note that any remaining loops will be reported by the “Check model” function described below.

4.4 Check model

After importing a model from Excel/Json files there can be unspecified relations which have to be defined. To check the model for these kind of relations, click the “Check model” button:

The same button can be used to check for issues with a model imported from Capella.

4.5 Download knowledge graph

The knowledge graph can be downloaded to a yEd diagram via the “Download graph” button:

After loading the exported model in yEd all nodes are on top of each other. Use the auto-layout tools of yEd to place all nodes in the diagram:

1. Select “Tools” → “Fit Node to Label” to scale each node to fit its label
2. Select “Layout” → “Hierarchical” to position the nodes in the diagram

For both actions the default options work fine. An example is shown in the following video:

yEd is available online via https://www.yworks.com/products/yed.

5 Diagnoser

The diagnoser can be started from the main editor window by clicking the “Diagnoser” button:

This will open the diagnoser window which consists of five sections:

1. Diagnoses: shows the current diagnosis (healthy or broken) for the top 10 most likely broken hardware parts.
2. Diagnostic tests: lists the next suggested tests. The first test will give the best balance between costs and gained information for the diagnosis.
   • The tests are ordered by balancing their information gain and cost. This balance can be moved to either more towards information gain (entropy) or more towards cost by using the balance-slider at the top of the screen.
3. Operating modes: enables you to select which operating mode is active for the system being diagnosed.
4. Direct observables: allows you to set which direct observables are reported to be Ok or NOk.
5. Evidence (not shown in figure below): lists all entered evidence during the diagnostic process.

An example of the diagnoser window for the CD-radio-player is shown below:

The video below demonstrates how to use the diagnoser using the CD-radio-player example. First the observations of the system are entered. The system is using battery power, hence the operating mode is set to BatteryPower. The power LED is blinking, indicating a problem with the power system, therefore the direct observable PowerLED is set to NOk. With this information entered the first diagnosis can be computed by clicking Compute.

The Diagnoses and Diagnostic tests sections will now be filled based on the available information. The first suggested test is Test_DistributePower which we specify to be NOk. The next suggested test is Test_Battery which we set to Ok. This leads to the final diagnosis in which the PowerBoard is found to be broken.

6 Design for diagnostics

Design for diagnostics can be started from the main editor window by clicking the “Design for diagnostics” button:

This will open the design for diagnostics window which allows users to select the operating mode(s) for which design for diagnostics will be computed. The results are split in two main parts:

1. Signatures shows for each hardware node and failure (state) combination how the direct observables will look like, and in which diagnostic procedure (DP) this combination is placed.
2. Diagnostic procedures shows for each diagnostic procedure which tests should be performed to diagnose a problem. This is also shown in the diagnostic tree below the table.

The video below demonstrates how the design for diagnostics results look like for the CD-radio-player example when the operating mode is set to WallPower.

7 Contact

MBDlyb is developed by the TNO-ESI diagnostics team. For more information or questions about the library and the methodology supported by it, please contact Thomas Nägele.