Modelica.Blocks.Tables

Library of blocks to interpolate in one and two-dimensional tables

Information

This package contains blocks for one- and two-dimensional interpolation in tables.

Special interest topic: Statically stored tables for real-time simulation targets

Especially for use on real-time platform targets (e.g., HIL-simulators) with no file system, it is possible to statically store tables using a function "usertab" in a file conventionally named "usertab.c". This can be more efficient than providing the tables as Modelica parameter arrays.

This is achieved by providing the tables in a specific structure as C-code and compiling that C-code together with the rest of the simulation model into a binary that can be executed on the target platform. The "Resources/Data/Tables/" subdirectory of the MSL installation directory contains the files "usertab.c" and "usertab.h" that can be used as a template for own developments. While "usertab.c" would be typically used unmodified, the "usertab.h" needs to adapted for the own needs.

In order to work it is necessary that the compiler pulls in the "usertab.c" file. Different Modelica tools might provide different mechanisms to do so. Please consult the respective documentation/support for your Modelica tool.

A possible (though a bit "hackish") Modelica standard conformant approach is to pull in the required files by utilizing a "dummy"-function that uses the Modelica external function interface to pull in the required "usertab.c". An example how this can be done is given below.

model Test25_usertab "Test utilizing the usertab.c interface"
  extends Modelica.Icons.Example;
public
  Modelica.Blocks.Sources.RealExpression realExpression(y=getUsertab(t_new.y))
    annotation (Placement(transformation(extent={{-40,-34},{-10,-14}})));
  Modelica.Blocks.Tables.CombiTable1D t_new(tableOnFile=true, tableName="TestTable_1D_a")
    annotation (Placement(transformation(extent={{-40,0},{-20,20}})));
  Modelica.Blocks.Sources.Clock clock
    annotation (Placement(transformation(extent={{-80,0},{-60,20}})));
protected
  encapsulated function getUsertab
    input Real dummy_u[:];
    output Real dummy_y;
    external "C" dummy_y=  mydummyfunc(dummy_u);
    annotation(IncludeDirectory="modelica://Modelica/Resources/Data/Tables",
           Include = "#include "usertab.c"
double mydummyfunc(double* dummy_in) {
   return 0;
}
");
  end getUsertab;
equation
  connect(clock.y,t_new. u[1]) annotation (Line(
      points={{-59,10},{-42,10}},
      color={0,0,127}));
  annotation (experiment(StartTime=0, StopTime=5), uses(Modelica(version="3.2.2")));
end Test25_usertab;

Extends from Modelica.Icons.Package (Icon for standard packages).

Package Content

Name Description
Modelica.Blocks.Tables.CombiTable1D CombiTable1D Table look-up in one dimension (matrix/file) with n inputs and n outputs
Modelica.Blocks.Tables.CombiTable1Ds CombiTable1Ds Table look-up in one dimension (matrix/file) with one input and n outputs
Modelica.Blocks.Tables.CombiTable2D CombiTable2D Table look-up in two dimensions (matrix/file)

Modelica.Blocks.Tables.CombiTable1D Modelica.Blocks.Tables.CombiTable1D

Table look-up in one dimension (matrix/file) with n inputs and n outputs

Information

Linear interpolation in one dimension of a table. Via parameter columns it can be defined how many columns of the table are interpolated. If, e.g., columns={2,4}, it is assumed that 2 input and 2 output signals are present and that the first output interpolates the first input via column 2 and the second output interpolates the second input via column 4 of the table matrix.

The grid points and function values are stored in a matrix "table[i,j]", where the first column "table[:,1]" contains the grid points and the other columns contain the data to be interpolated. Example:

   table = [0,  0;
            1,  1;
            2,  4;
            4, 16]
   If, e.g., the input u = 1.0, the output y =  1.0,
       e.g., the input u = 1.5, the output y =  2.5,
       e.g., the input u = 2.0, the output y =  4.0,
       e.g., the input u =-1.0, the output y = -1.0 (i.e., extrapolation).

The table matrix can be defined in the following ways:

  1. Explicitly supplied as parameter matrix "table", and the other parameters have the following values:
       tableName is "NoName" or has only blanks,
       fileName  is "NoName" or has only blanks.
    
  2. Read from a file "fileName" where the matrix is stored as "tableName". Both ASCII and MAT-file format is possible. (The ASCII format is described below). The MAT-file format comes in four different versions: v4, v6, v7 and v7.3. The library supports at least v4, v6 and v7 whereas v7.3 is optional. It is most convenient to generate the MAT-file from FreeMat or MATLAB® by command
       save tables.mat tab1 tab2 tab3
    
    or Scilab by command
       savematfile tables.mat tab1 tab2 tab3
    
    when the three tables tab1, tab2, tab3 should be used from the model.
    Note, a fileName can be defined as URI by using the helper function loadResource.
  3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks. Row-wise storage is always to be preferred as otherwise the table is reallocated and transposed. See the Tables package documentation for more details.

When the constant "NO_FILE_SYSTEM" is defined, all file I/O related parts of the source code are removed by the C-preprocessor, such that no access to files takes place.

If tables are read from an ASCII-file, the file needs to have the following structure ("-----" is not part of the file content):

-----------------------------------------------------
#1
double tab1(5,2)   # comment line
  0   0
  1   1
  2   4
  3   9
  4  16
double tab2(5,2)   # another comment line
  0   0
  2   2
  4   8
  6  18
  8  32
-----------------------------------------------------

Note, that the first two characters in the file need to be "#1" (a line comment defining the version number of the file format). Afterwards, the corresponding matrix has to be declared with type (= "double" or "float"), name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. The elements have to be provided as a sequence of numbers in row-wise order (therefore a matrix row can span several lines in the file and need not start at the beginning of a line). Numbers have to be given according to C syntax (such as 2.3, -2, +2.e4). Number separators are spaces, tab ( ), comma (,), or semicolon (;). Several matrices may be defined one after another. Line comments start with the hash symbol (#) and can appear everywhere. Other characters, like trailing non comments, are not allowed in the file.

MATLAB is a registered trademark of The MathWorks, Inc.

Extends from Modelica.Blocks.Interfaces.MIMOs (Multiple Input Multiple Output continuous control block with same number of inputs and outputs).

Parameters

NameDescription
nNumber of inputs (= number of outputs)
Table data definition
tableOnFile= true, if table is defined on file or in function usertab
table[:, :]Table matrix (grid = first column; e.g., table=[0,2])
tableNameTable name on file or in function usertab (see docu)
fileNameFile where matrix is stored
verboseRead= true, if info message that file is loading is to be printed
Table data interpretation
columns[:]Columns of table to be interpolated
smoothnessSmoothness of table interpolation

Connectors

NameDescription
u[n]Connector of Real input signals
y[n]Connector of Real output signals

Modelica.Blocks.Tables.CombiTable1Ds Modelica.Blocks.Tables.CombiTable1Ds

Table look-up in one dimension (matrix/file) with one input and n outputs

Information

Linear interpolation in one dimension of a table. Via parameter columns it can be defined how many columns of the table are interpolated. If, e.g., icol={2,4}, it is assumed that one input and 2 output signals are present and that the first output interpolates via column 2 and the second output interpolates via column 4 of the table matrix.

The grid points and function values are stored in a matrix "table[i,j]", where the first column "table[:,1]" contains the grid points and the other columns contain the data to be interpolated. Example:

   table = [0,  0;
            1,  1;
            2,  4;
            4, 16]
   If, e.g., the input u = 1.0, the output y =  1.0,
       e.g., the input u = 1.5, the output y =  2.5,
       e.g., the input u = 2.0, the output y =  4.0,
       e.g., the input u =-1.0, the output y = -1.0 (i.e., extrapolation).

The table matrix can be defined in the following ways:

  1. Explicitly supplied as parameter matrix "table", and the other parameters have the following values:
       tableName is "NoName" or has only blanks,
       fileName  is "NoName" or has only blanks.
    
  2. Read from a file "fileName" where the matrix is stored as "tableName". Both ASCII and MAT-file format is possible. (The ASCII format is described below). The MAT-file format comes in four different versions: v4, v6, v7 and v7.3. The library supports at least v4, v6 and v7 whereas v7.3 is optional. It is most convenient to generate the MAT-file from FreeMat or MATLAB® by command
       save tables.mat tab1 tab2 tab3
    
    or Scilab by command
       savematfile tables.mat tab1 tab2 tab3
    
    when the three tables tab1, tab2, tab3 should be used from the model.
    Note, a fileName can be defined as URI by using the helper function loadResource.
  3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks. Row-wise storage is always to be preferred as otherwise the table is reallocated and transposed. See the Tables package documentation for more details.

When the constant "NO_FILE_SYSTEM" is defined, all file I/O related parts of the source code are removed by the C-preprocessor, such that no access to files takes place.

If tables are read from an ASCII-file, the file needs to have the following structure ("-----" is not part of the file content):

-----------------------------------------------------
#1
double tab1(5,2)   # comment line
  0   0
  1   1
  2   4
  3   9
  4  16
double tab2(5,2)   # another comment line
  0   0
  2   2
  4   8
  6  18
  8  32
-----------------------------------------------------

Note, that the first two characters in the file need to be "#1" (a line comment defining the version number of the file format). Afterwards, the corresponding matrix has to be declared with type (= "double" or "float"), name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. The elements have to be provided as a sequence of numbers in row-wise order (therefore a matrix row can span several lines in the file and need not start at the beginning of a line). Numbers have to be given according to C syntax (such as 2.3, -2, +2.e4). Number separators are spaces, tab ( ), comma (,), or semicolon (;). Several matrices may be defined one after another. Line comments start with the hash symbol (#) and can appear everywhere. Other characters, like trailing non comments, are not allowed in the file.

MATLAB is a registered trademark of The MathWorks, Inc.

Extends from Modelica.Blocks.Interfaces.SIMO (Single Input Multiple Output continuous control block).

Parameters

NameDescription
noutNumber of outputs
Table data definition
tableOnFile= true, if table is defined on file or in function usertab
table[:, :]Table matrix (grid = first column; e.g., table=[0,2])
tableNameTable name on file or in function usertab (see docu)
fileNameFile where matrix is stored
verboseRead= true, if info message that file is loading is to be printed
Table data interpretation
columns[:]Columns of table to be interpolated
smoothnessSmoothness of table interpolation

Connectors

NameDescription
uConnector of Real input signal
y[nout]Connector of Real output signals

Modelica.Blocks.Tables.CombiTable2D Modelica.Blocks.Tables.CombiTable2D

Table look-up in two dimensions (matrix/file)

Information

Linear interpolation in two dimensions of a table. The grid points and function values are stored in a matrix "table[i,j]", where:

Example:

           |       |       |       |
           |  1.0  |  2.0  |  3.0  |  // u2
       ----*-------*-------*-------*
       1.0 |  1.0  |  3.0  |  5.0  |
       ----*-------*-------*-------*
       2.0 |  2.0  |  4.0  |  6.0  |
       ----*-------*-------*-------*
     // u1
   is defined as
      table = [0.0,   1.0,   2.0,   3.0;
               1.0,   1.0,   3.0,   5.0;
               2.0,   2.0,   4.0,   6.0]
   If, e.g., the input u is [1.0;1.0], the output y is 1.0,
       e.g., the input u is [2.0;1.5], the output y is 3.0.

The table matrix can be defined in the following ways:

  1. Explicitly supplied as parameter matrix "table", and the other parameters have the following values:
       tableName is "NoName" or has only blanks,
       fileName  is "NoName" or has only blanks.
    
  2. Read from a file "fileName" where the matrix is stored as "tableName". Both ASCII and MAT-file format is possible. (The ASCII format is described below). The MAT-file format comes in four different versions: v4, v6, v7 and v7.3. The library supports at least v4, v6 and v7 whereas v7.3 is optional. It is most convenient to generate the MAT-file from FreeMat or MATLAB® by command
       save tables.mat tab1 tab2 tab3
    
    or Scilab by command
       savematfile tables.mat tab1 tab2 tab3
    
    when the three tables tab1, tab2, tab3 should be used from the model.
    Note, a fileName can be defined as URI by using the helper function loadResource.
  3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks. Row-wise storage is always to be preferred as otherwise the table is reallocated and transposed. See the Tables package documentation for more details.

When the constant "NO_FILE_SYSTEM" is defined, all file I/O related parts of the source code are removed by the C-preprocessor, such that no access to files takes place.

If tables are read from an ASCII-file, the file needs to have the following structure ("-----" is not part of the file content):

-----------------------------------------------------
#1
double table2D_1(3,4)   # comment line
0.0  1.0  2.0  3.0  # u[2] grid points
1.0  1.0  3.0  5.0
2.0  2.0  4.0  6.0

double table2D_2(4,4)   # comment line
0.0  1.0  2.0  3.0  # u[2] grid points
1.0  1.0  3.0  5.0
2.0  2.0  4.0  6.0
3.0  3.0  5.0  7.0
-----------------------------------------------------

Note, that the first two characters in the file need to be "#1" (a line comment defining the version number of the file format). Afterwards, the corresponding matrix has to be declared with type (= "double" or "float"), name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. The elements have to be provided as a sequence of numbers in row-wise order (therefore a matrix row can span several lines in the file and need not start at the beginning of a line). Numbers have to be given according to C syntax (such as 2.3, -2, +2.e4). Number separators are spaces, tab ( ), comma (,), or semicolon (;). Several matrices may be defined one after another. Line comments start with the hash symbol (#) and can appear everywhere. Other characters, like trailing non comments, are not allowed in the file. The matrix elements are interpreted in exactly the same way as if the matrix is given as a parameter. For example, the first column "table2D_1[2:,1]" contains the u[1] grid points, and the first row "table2D_1[1,2:]" contains the u[2] grid points.

MATLAB is a registered trademark of The MathWorks, Inc.

Extends from Modelica.Blocks.Interfaces.SI2SO (2 Single Input / 1 Single Output continuous control block).

Parameters

NameDescription
Table data definition
tableOnFile= true, if table is defined on file or in function usertab
table[:, :]Table matrix (grid u1 = first column, grid u2 = first row; e.g., table=[0,0;0,1])
tableNameTable name on file or in function usertab (see docu)
fileNameFile where matrix is stored
verboseRead= true, if info message that file is loading is to be printed
Table data interpretation
smoothnessSmoothness of table interpolation

Connectors

NameDescription
u1Connector of Real input signal 1
u2Connector of Real input signal 2
yConnector of Real output signal
Automatically generated Tue Apr 05 09:36:13 2016.