[Contents] [TitleIndex] [WordIndex] 

Xcos/SysML : implementation of a bi-directionnal mapping

/!\ remarks:

Introduction to Scilab / Xcos

The main diagram

Here is a simple Xcos diagram from the Scilab demonstration menu (Go to Xcos Demos menu, then select "Control System" / "Water Tank").

xcos_demo_watertank.png

Each block can be connected to each other with two different kinds of link.

Here is an example of a block with one event input and two data inputs:

xcos_cmscope.png

The superblock diagram : a nested diagram

A special case of block in Xcos diagram is the superblock block. The role of a superblock is to encapsulate a nested Xcos diagram. A superblock in Xcos is represented by this following picture :

xcos_superblock.png

When double-clicking on the superblock, here is the diagram we can see. One must bear in mind, in this case, the superblock Xcos diagram has one input block and one output block. It should be aligned in the upper diagram with the super block which have one input data port and one output data port.

xcos_demo_watertank_superblock.png

The simulation parameters

Most of the blocks can accept user-defined values. For example, the clock block has the following parameters:

xcos_bounce_diagram_clock_dialog.png

For storing user defined values and other values needed for the simulation, every Xcos block has internal parameters. In Xcos format, these parameters are represented by either string matrices, float matrices or integer matrices.

Finally, every Xcos simulation has parameters to set the beginning time, the end time and tolerances of the simulation. In Xcos editor, you can access these parameters via the menu "Simulation" / "Setup". Here is a snapshot of the simulation dialog:

xcos_setup_window.png

In Xcos editor, you can specify the context of the diagram. By setting the context, we mean variable initialization for instance. This is accessible by selecting the menu "Simulation" / "Set Context". Here is a snapshot:

xcos_set_context.png

When debugging Xcos simulation, it could be useful to generate debug information. This is accessible via the menu "Simulation" / "Execution Trace And Debug". Here is a snapshot of the dialog window:

Xcos_Execution_Trace_And_Debug.png

Mapping from Xcos diagrams to SysML using block definition diagrams and internal block diagrams

Mapping between the main Xcos Diagram and SysML

Block Definition Diagram

As explained on the SysML specification, the Block Definition Diagram in SysML defines features of blocks and relationships between blocks such as associations, generalizations, and dependencies. It captures the definition of blocks in terms of properties and operations, and relationships such as a system hierarchy or a system classification tree.

Here is the equivalent block definition diagram edited in Papyrus which represents the Xcos "Water Tank" demonstration. This is a fisrt step mapping. This diagram is not final and is an intermediate one. All the Xcos information are not present in this papyrus diagram.

papyrus_demo_watertank_schema.png

As you can see, the block definition diagram is composed of eleven SysML blocks.

Each block in Xcos diagram has internal properties. Each parameter of an Xcos block will be mapped within a block property. Here is the example of the CONST_m Xcos block mapped with all its properties in SysML.

block_parameters.PNG

In Papyrus, the simulation information such as the context, the solvers, etc should be modelised by a parent block. This parent block should have properties which describes these information needed for simulation:

papyrus_parentBlock.png

Here is the final block definition diagram of the main Scilab/Xcos diagram. In this diagram, we can see that the parent block is composed of all the simulation blocks.

papyrus_bdd_composition.png

8.3.2.2 Block::isEncapsulated

The block is treated as a black box, so always set it true for blocks with a native implementation. For super-blocks ones, set isEncapsulated=false and provide the implementation as internal block diagram. For mixed implementation, this flag can be used as a switch to choose the implementation (internal or native one).

Internal Block Diagram

As described in the SysML specification, the Internal Block Diagram in SysML captures the internal structure of a block in terms of properties and connectors between properties. A block can include properties to specify its values, parts, and references to other blocks.

Here is the equivalent internal block diagram which represents the roles of the blocks between each other.

papyrus_demo_watertank_ibd.png

As you can see, the internal block diagram is composed of eleven SysML parts.

Concerning part flowports, when translating an Xcos diagram into a SysML internal block diagram, let's use the following rules:

9.3.2.2 FlowPort::isAtomic (SysML 1.2)

By default, this attribute should always be set to True.

9.3.2.2 FlowPort::FlowDirection (SysML 1.2)

As mentionned in introduction, ports are either event ports or data ports.

Data ports are divided into two sub-categories:

Here is an exemple of explicit ports in an Scilab/Xcos diagram :

xcos_gainblk.png

Here is an exemple of implicit ports in an Scilab/Xcos diagram :

xcos_resistor.png

Indeed, differential equations can be divided in two parts:

When a modelica description is used, Xcos use a modelica compiler to transform the implicit differential equation into a set of explicit differential equations. The modelica implicit equation description is then replaced by the new explicit differential equations. The diagram could then be simulated using xcos traditionnal solvers.

For event ports, Flowdirection cannot be "inout". The possible values are only "in" and "out".

Concerning block flow ports, when translating an Xcos diagram into a SysML diagram, let's use the following rules:

9.3.2.2 FlowPort::isConjugated (SysML 1.2)

This attribute should always be set to False.

B.4 Transitioning SysML 1.2 Flow Ports to SysML 1.3 Ports

As explained in annexe B.4, flow ports are deprecated since SysML 1.3. In our case, we will only follow step 1) 2) 4) of the guidelines.

Mapping between the superblock diagram and SysML

Block Definition diagram

Here is the Papyrus translation block definition diagram of the superblock diagram. This is a first step mapping. This diagram is an intermediate one. The aim of this diagram is to show the steps into mapping an Xcos diagram into SysML.

papyrus_demo_watertank_superblock_diagram.png

A superblock diagram has simulation parameters such as its context. As seen in previous section with the main block definition diagram, these information are stored in a parent block. The relationship between parent block and the simulation blocks is a composition relationship. Here is the final block definition diagram of the nested superblock diagram.

papyrus_demo_watertank_superblock_diagram_composition.png

Internal Block Diagram

One must bear in mind, the block definition diagram does not capture the roles between Xcos Blocks. We have to introduce the internal block diagram in order to precise the role of the Xcos blocks between each others. Here, you can find the internal block diagram of the nested superblock diagram. For information, the internal block diagram of the superblock has one external flowport which direction is "in" and one external flowport which direction is "out". This is coherent with the upper internal block diagram where the SUPER_f block has one "in" flowport and one "out" flowport.

papyrus_superblock_ibd.png

Mapping from Xcos diagrams to SysML using activity diagrams

Here is an example of mapping of the Scilab/Xcos "Water tank" demonstration :

WaterTank.PNG

Mapping a Simple Xcos block

Each Xcos block is mapped into a call-behaviour item which points to an activity defined in a library. A call behavior action may be added to a SysML activity diagram to invoke the behavior of another activity, previously specified in its own activity diagram.

For instance in the Scilab/Xcos diagram, the SUMMATION block has two data inputs and one input data. In the SysML library, the corresponding activity has thus two parameters set as input and one parameter set as output.

Mapping the Xcos block parameters

User can set attributes of Xcos block by double-clicking on the block for example. In our Xcos diagram example, if user double-click on the PID Xcos block, a dialog window is opened and user is told to enter its values of proportional gain, integral gain and derivative gain.

xcos_PID_dialog.png

Under Papyrus, we will use the eannotations of the activity pointed by the call-behaviour item.

Mapping a Superblock Xcos block

For a superblock, the idea is the same. A superblock is mapped with a call-behaviour which points to a nested activity diagram. The number of inputs and outputs of the super block call behaviour and the nested activity diagram should be coherent. In our above mapping example, the superblock is represented in red colour.

Here you can find the mapped encapsulated SysML diagram edited with Papyrus :

SUPER_f.PNG

Xcos has two different kinds of link between blocks

For example, in the water tank Scilab/Xcos demonstration, the CMSCOPE block has two input data ports and one event port.

xcos_cmscope.png

In SysML diagram, these links will be mapped by object flows.

If the xcos link deals with event, then the corresponding object flow will get a Discrete stereotype. To the contrary, if the xcos link deals with data, then the corresponding object flow will get a Continuous stereotype.

When mapping the links between the call-behaviour items with object flows, we will use the following rules :

Mapping the Xcos schema specific information

An Xcos schema has specific data used for all blocks such as solver, solver tolerances, end of simulation time, etc...

Here is the Scilab/Xcos simulation setup used to set these parameters:

xcos_setup_window.png

For such information, we chose to map all these information as EAnnotation of the root activity in Papyrus.

Mapping an optimization use case

AgeSys usecase

Here is the use case:

  1. The system designer is using Papyrus
    1. He creates a block with a given number of inputs and types
    2. He defines the parameters which would be proprieties under Papyrus
    3. He asks the automaticien to define theses parameters for a given configuration
  2. The domain-specific expert is using Xcos
    1. He imports the parametric block as a superblock
    2. He implements the superblock in Xcos
    3. He finds a solution to determine the parameter using optimisation or manually
  3. The system designer is using Papyrus
    1. He imports the Xcos diagram as an extern documentation item
    2. He imports the found parameters values in Papyrus
    3. He uses Papyrus to have a high-level view of the project

We have been thinking about this use case. However the parametric diagram is not available in Papyrus.

Here is the definition of the parametric diagram as shown in 10.3.1.2 of SysML specification

Here is a parametric diagram from the SysML 1.3 specification :

parametric_from_spec.png

Assuming step 1 is achieved for the w:TotalWeight constraint block, the domain-specific expert imports that SysML block into a superblock in Xcos (step 2.1). Its first role is to implement this superblock in Xcos. The superblock imported in Xcos has four inputs and one output.

superblock_parametric.png

Here is the implementation of the Xcos superblock (step 2.2).

superblock_implementation_parametric.png

We can notice that the implementation is coherent with the superblock itself. We can imagine that the domain-specific expert simulates then the overall system and finds the best parameters that fit its model (step 2.3)

Then in step 3, the system designer imports the xcos diagram in Papyrus, imports the found best parameters values and navigates through the SysML project.

When the system designer has no idea of what could be an input or output, he can use implicit ports. Here is the same example from the SysML specification parametric diagram. The system designer is interested by w:TotalWeight but every parameters could be an input or an output (step 1.1 1.2 1.3). Here is the superblock diagram when imported from SysML (step 2.1) :

implicit_superblock.png

The domain-specific expert could implement this nested diagram of the superblock like this :

implicit_superblock_implementation.png

One must bear in mind that Xcos port used for that implementation are square ports. It means they are implicit. There is no given direction for the data flowing throw these kind of ports.

We have added in next part an optimization process in Scilab/Xcos which could give an idea of optimization process using Scilab / Xcos.

Example of optimization using Scilab/Xcos

Here is the modified "Water tank" demonstration used to optimize the Proportional Integral Derivative controler used to regulate the water tank level.

xcos_demo_watertank_automatic.png

The variable parameters are set in the context of the root diagram P, I, D as shown in the PID user-defined values dialog window.

xcos_PID_window.png

First, we initialize Xcos by loading some important Xcos libraries (done by calling loadXcosLibs()). Then, we load our diagram using importXcosDiagram. 

// load important libs and diagram
loadXcosLibs();

importXcosDiagram('demo_watertank_automatic.xcos');

Let's define some parameters. 

// Let's define some parameters
MaxEvalFunc = 10;
Pfact  = 1.0;
Ifact = 1.0;
Dfact  = 1.0;
h_step = 1e-3;  // the delta used to compute finite difference derivative
x0     = [1;1;1]; // Initial parameters
                // P is proportionnal to Pfact
                // I is proportionnal t  Ifact
                // D is proportionnal to Dfact
Lower = [0.01; 0.01; 0.01];
Upper = [10; 10; 10];

global Iter;
Iter = 0;

Once this is done, we define two functions:

The objective function (we minimize the error between the reference signal (the square generator) and the output signal. We also try to minimize the derivative of the output signal (so as ta have some kind of smooth command). 

function y = f_pid(x)
  global Iter;
  %scicos_context.P  = x(1)*Pfact;
  %scicos_context.I  = x(2)*Ifact;
  %scicos_context.D  = x(3)*Dfact;
  Iter = Iter + 1;
  Info = scicos_simulate(scs_m,list(),%scicos_context,flag='nw');
  y_error = mean(abs((block_output('values')(:,1) -  block_output('values')(:,2))));
  y_diff  = mean(abs(diff(block_output('values')(:,2))));
  y = 0.5*y_error + 0.5*1*y_diff; ...
  printf('Evaluation %d - P = %f I = %f D = %f y = %f (y_error = %f, y_diff = %f)\n', Iter, x(1), x(2), x(3), y, y_error, y_diff);
endfunction

For the optim wrapper, we compute the value of the objective function and the gradient (using the Scilab derivative function). 

function [f,df,ind] = my_optim_pid(x,ind)
  f  = f_pid(x);
  df = derivative(f_pid,x,h=h_step,order=4);
endfunction

Once these functions are defined, we launch a first simulation to see the initial behavior. 

%scicos_context = [];
%scicos_context.P = Pfact*x0(1);
%scicos_context.I = Pfact*x0(2);
%scicos_context.D = Dfact*x0(3);
Info = scicos_simulate(scs_m,list(),%scicos_context,'nw');

Here is the initial behaviour with default PID values:

xcos_default_PID_regulation_scope.png

Now, we launch the optimization. 

[f_opt, x_opt] = optim(my_optim_pid,'b',Lower,Upper,x0,algo='qn','ar',MaxEvalFunc,MaxEvalFunc,1e-3,1e-3,[1e-3;1e-3;1e-3]);

Finally, we launch a simulation using the optimized parameters to see the behaviour of the loop. 

%scicos_context.P = x_opt(1)*Pfact;
%scicos_context.I = x_opt(2)*Ifact;
%scicos_context.D = x_opt(3)*Dfact;

Info = scicos_simulate(scs_m,list(),%scicos_context);

Here is the water tank optimized level water scope:

xcos_optimized_water_level_regulation.png

References

CategoryXcos

2022-09-08 09:27