# CombiTable2D

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

Modelica/Blocks/Tables

## Description

Bivariate constant, bilinear or bivariate Akima interpolation of a two-dimensional table. The grid points and function values are stored in a matrix "table[i,j]", where:

• the first column "table[2:,1]" contains the u1 grid points,
• the first row "table[1,2:]" contains the u2 grid points,
• the other rows and columns contain the data to be interpolated.

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 u1 is 1.0, input u2 is 1.0 and smoothness is LinearSegments, the output y is 1.0,
e.g., the input u1 is 2.0, input u2 is 1.5 and smoothness is LinearSegments, the output y is 3.0.

• The interpolation interval is found by a binary search where the interval used in the last call is used as start interval.
• Via parameter smoothness it is defined how the data is interpolated:
  smoothness = 1: Bilinear interpolation
= 2: Bivariate Akima interpolation: Smooth interpolation by bicubic Hermite
splines such that der(y) is continuous, also if extrapolated.
= 3: Constant segments
= 4: Fritsch-Butland interpolation: Not supported
= 5: Steffen interpolation: Not supported

• Values outside of the table range, are computed by extrapolation according to the setting of parameter extrapolation:
  extrapolation = 1: Hold the first or last values of the table,
if outside of the table scope.
= 2: Extrapolate by using the derivative at the first/last table
points if outside of the table scope.
(If smoothness is LinearSegments or ConstantSegments
this means to extrapolate linearly through the first/last
two table points.).
= 3: Periodically repeat the table data (periodical function).
= 4: No extrapolation, i.e. extrapolation triggers an error

• If the table has only one element, the table value is returned, independent of the value of the input signal.
• If the input signal u1 or u2 is outside of the defined interval, the corresponding value is also determined by linear interpolation through the last or first two points of the table.
• The grid values (first column and first row) have to be strictly increasing.

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 text and MATLAB MAT-file format is possible. (The text 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 a text 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 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 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 (\\t), comma (,), or semicolon (;). Several matrices may be defined one after another. Line comments start with the hash symbol (#) and can appear everywhere. Text files should either be ASCII or UTF-8 encoded, where UTF-8 encoded strings are only allowed in line comments and an optional UTF-8 BOM at the start of the text file is ignored. 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 grid points, and the first row "table2D_1[1,2:]" contains the u grid points.

MATLAB is a registered trademark of The MathWorks, Inc.

## Parameters NameLabelDescriptionData TypeValid Values

mo_tableOnFile

tableOnFile

= true, if table is defined on file or in function usertab

Scalar

true
false

mo_table

table

Table matrix (grid u1 = first column, grid u2 = first row; e.g., table=[0, 0; 0, 1])

Matrix

mo_tableName

tableName

Table name on file or in function usertab (see docu)

String

mo_fileName

fileName

File where matrix is stored

String

= true, if info message that file is loading is to be printed

Scalar

true
false

mo_smoothness

smoothness

Smoothness of table interpolation

Structure

mo_smoothness/choice1

Table points are linearly interpolated

Number

0
1

mo_smoothness/choice2

Table points are interpolated (by Akima splines) such that the first derivative is continuous

Number

0
1

mo_smoothness/choice3

Table points are not interpolated, but the value from the previous abscissa point is returned

Number

0
1

mo_smoothness/choice4

Table points are interpolated (by Fritsch-Butland splines) such that the monotonicity is preserved and the first derivative is continuous

Number

0
1

mo_smoothness/choice5

Table points are interpolated (by Steffen splines) such that the monotonicity is preserved and the first derivative is continuous

Number

0
1

mo_extrapolation

extrapolation

Extrapolation of data outside the definition range

Structure

mo_extrapolation/choice1

Hold the first/last table point outside of the table scope

Number

0
1

mo_extrapolation/choice2

Extrapolate by using the derivative at the first/last table points outside of the table scope

Number

0
1

mo_extrapolation/choice3

Repeat the table scope periodically

Number

0
1

mo_extrapolation/choice4

Extrapolation triggers an error

Number

0
1

mo_verboseExtrapolation

verboseExtrapolation

= true, if warning messages are to be printed if table input is outside the definition range

Scalar

true
false

mo_u_min

u_min

Minimum abscissa value defined in table

Vector of size 2

mo_u_max

u_max

Maximum abscissa value defined in table

Vector of size 2

mo_tableID

tableID

External table object

Scalar NameLabelDescriptionData TypeValid Values

mo_u1

u1

u1

Structure

mo_u1/fixed

fixed

Cell of scalars

true
false

mo_u1/start

start

Cell of scalars

mo_u2

u2

u2

Structure

mo_u2/fixed

fixed

Cell of scalars

true
false

mo_u2/start

start

Cell of scalars

mo_y

y

y

Structure

mo_y/fixed

fixed

Cell of scalars

true
false

mo_y/start

start

Cell of scalars

## Ports

NameTypeDescriptionIO TypeNumber

u1

implicit

Connector of Real input signal 1

input

1

u2

implicit

Connector of Real input signal 2

input

2

y

implicit

Connector of Real output signal

output

1