## ModelicaAdditions.Tables

### Information

This package contains components to interpolate linearly in tables. Table data may optionally be read in from files (ASCII or Matlab-4 binary format). This package contains the following components:

       CombiTableTime  Table look-up with time as abszissa
       CombiTableTime2 Table look-up with time as abszissa and
                       linear/perodic extrapolation methods
       CombiTable1D    Table look-up in one dimension
       CombiTable1Ds   Table look-up in one dimension with
                       same input for different coloumns
       CombiTable2D    Table look-up in two dimensions

This package is not part of the Modelica standard library, because it is planned to realize a package with better and more general table support based on a different design.

Main Author:
  Martin Otter
  Deutsches Zentrum für Luft und Raumfahrt e.V. (DLR)
  Institut für Robotik und Mechatronik
  Postfach 1116
  D-82230 Wessling
  Germany
  email: Martin.Otter@dlr.de

Release Notes:

- October 21, 2002 by Martin Otter and Christian Schweiger:
  Added component CombiTable1Ds with single input and multiple output. Example updated.
- March 31, 2001 by Martin Otter:
  New component CombiTableTime2 (used CombiTableTime as a basis and added the arguments extrapolation, columns, startTime. This allows periodic function definitions). Bug fixed for CombiTableTime, when table is read from file and starting time is not within the first interval of the table.
- June 11, 2000 by Martin Otter:
  Realized based on an existing Dymola library of Martin Otter.

Copyright © 2000-2002, DLR.

The ModelicaAdditions.Tables package is free software; it can be redistributed and/or modified under the terms of the Modelica license, see the license conditions and the accompanying disclaimer in the documentation of package Modelica in file "Modelica/package.mo".

## ModelicaAdditions.Tables.CombiTableTime

Table look-up with time as abszissa (matrix/file)

### Information

Linear interpolation in a table with respect to time. Via parameter icol it can be defined how many columns of the table are interpolated. If, e.g., icol={2,4}, it is assumed that 2 output signals are present and that the first output is computed by interpolation of column 2 and the second output is computed by interpolation of column 4 of the table matrix.

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

       table = [0,  0;
                1,  0;
                1,  1;
                2,  4;
                3,  9;
                4, 16]

      If, e.g., time = 1.0, the output y =  0.0 (before event), 1.0 (after event)
          e.g., time = 1.5, the output y =  2.5,
          e.g., time = 2.0, the output y =  4.0,
          e.g., time = 5.0, the output y = 23.0 (i.e. extrapolation).

- If the table has only one row, the table value is returned, independently of time.
- If time is outside of the defined interval, i.e., time > table[size(table,1),1] or time < table[1,1], the corresponding value is also determined by linear interpolation through the last or first two points of the table.
- Two successive time instants may be identical (see table example) to define a discontinuous point in the function. At every defined time instant of the table, a time event occurs in order to not integrate over a discontinuous or not differentiable point. From the discussion follows that the time values in the first column of the table have to be monotonically (but NOT strict monotonically) 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 ASCII and binary file format is possible. (the ASCII format is described below). It is most convenient to generate the binary file from Matlab (Matlab 4 storage format), e.g., by command

          save tables.mat tab1 tab2 tab3 -V4

   when the three tables tab1, tab2, tab3 should be used from the model.
3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks.

Table definition methods (1) and (3) do not allocate dynamic memory, and do not access files, whereas method (2) does. Therefore (1) and (3) are suited for hardware-in-the-loop simulation (e.g. with dSpace hardware). When the constant "NO_FILE" is defined, all parts of the source code of method (2) are removed by the C-preprocessor, such that no dynamic memory allocation and no access to files takes place.

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

    -----------------------------------------------------
    #1
    double tab1(6,2)   # comment line
      0   0
      1   0
      1   1
      2   4
      3   9
      4  16

    double tab2(6,2)   # another comment line
      0   0
      2   0
      2   2
      4   8
      6  18
      8  32
    -----------------------------------------------------

Note, that the first two characters in the file need to be "#1". Afterwards, the corresponding matrix has to be declared with type, name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. Several matrices may be defined one after another.

### Parameters

Name | Default | Description
--- | --- | ---
table[:, :] | [0, 0; 1, 1] | table matrix (time = first column)
tableName | "NoName" | table name on file or in function usertab(optional)
fileName | "NoName" | file where matrix is stored (optional)
icol[:] | {2} | columns of table to be interpolated

### Modelica definition

    model CombiTableTime
      "Table look-up with time as abszissa (matrix/file) "
      parameter Real table[:, :]=[0, 0; 1, 1] "table matrix (time = first column)";
      parameter String tableName="NoName"
        "table name on file or in function usertab(optional)";
      parameter String fileName="NoName" "file where matrix is stored (optional)";
      parameter Real icol[:]={2} "columns of table to be interpolated";
      extends Modelica.Blocks.Interfaces.MO(final nout=size(icol, 1));
    protected
      Real tableID(start=0);
    equation
      when initial() then
        tableID = dymTableTimeIni(time, 0.0, tableName, fileName, table, 0.0);
      end when;

      /*Interpolate with respect to time.*/
      for i in 1:nout loop
        outPort.signal[i] = dymTableTimeIpo(tableID, icol[i], time);
      end for;

    end CombiTableTime;

## ModelicaAdditions.Tables.CombiTableTime2

Table look-up with respect to time and linear/perodic extrapolation methods (data from matrix/file)

### Information

This block generates an output signal by linear interpolation in a table. The time points and function values are stored in a matrix table[i,j], where the first column table[:,1] contains the time points and the other columns contain the data to be interpolated. Via parameter columns it can be defined which columns of the table are interpolated. If, e.g., columns={2,4}, it is assumed that 2 output signals are present and that the first output is computed by interpolation of column 2 and the second output is computed by interpolation of column 4 of the table matrix. The table interpolation has the following proporties:

- The time points need to be monotonically increasing.
- Discontinuities are allowed, by providing the same time point twice in the table.
- Values outside of the table range, are computed by extrapolation:

        extrapolation = 0: hold the first or last value of the table,
                           if outside of the range.
                      = 1: extrapolate through the last or first two
                           points of the table.
                      = 2: periodically repeat the table data
                           (periodical function).

- If the table has only one row, no interpolation is performed and the table values of this row are just returned.
- Via parameters startTime and offset the curve defined by the table can be shifted both in time and in the ordinate value. The time instants stored in the table are therefore relative to startTime. If time < startTime, no interpolation is performed and the offsets are used as ordinate values. If vector offset has only one element, this element is added as offset to all values of the columns selected by columns.
- The table is implemented in a numerically sound way by generating time events at interval boundaries, in order to not integrate over a discontinuous or not differentiable points.
- For special applications it is sometimes needed to know the minimum and maximum time instant defined in the table as a parameter. For this reason parameters t_min and t_max are provided and can be access from the outside of the table object.

Example:

       table = [0  0
                1  0
                1  1
                2  4
                3  9
                4 16]; extrapolation = 1 (default)

    If, e.g., time = 1.0, the output y =  0.0 (before event), 1.0 (after event)
        e.g., time = 1.5, the output y =  2.5,
        e.g., time = 2.0, the output y =  4.0,
        e.g., time = 5.0, the output y = 23.0 (i.e. extrapolation via last 2 points).

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 binary file format is possible. (the ASCII format is described below). It is most convenient to generate the binary file from Matlab (Matlab 4 storage format), e.g., by command

          save tables.mat tab1 tab2 tab3 -V4

   when the three tables tab1, tab2, tab3 should be used from the model.
3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks.

Table definition methods (1) and (3) do not allocate dynamic memory, and do not access files, whereas method (2) does. Therefore (1) and (3) are suited for hardware-in-the-loop simulation (e.g. with dSpace hardware). When the constant "NO_FILE" is defined, all parts of the source code of method (2) are removed by the C-preprocessor, such that no dynamic memory allocation and no access to files takes place.

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

    -----------------------------------------------------
    #1
    double tab1(6,2)   # comment line
      0   0
      1   0
      1   1
      2   4
      3   9
      4  16

    double tab2(6,2)   # another comment line
      0   0
      2   0
      2   2
      4   8
      6  18
      8  32
    -----------------------------------------------------

Note, that the first two characters in the file need to be "#1". Afterwards, the corresponding matrix has to be declared with type, name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. Several matrices may be defined one after another.

Release Notes:

- March 31, 2001 by Martin Otter:
  Used CombiTableTime as a basis and added the arguments extrapolation, columns, startTime. This allows periodic function definitions.

### Parameters

Name | Default | Description
--- | --- | ---
table[:, :] | [0, 0; 1, 1] | table matrix (time = first column)
tableName | "NoName" | table name on file or in function usertab(optional)
fileName | "NoName" | file where matrix is stored (optional)
columns[:] | 2:size(table, 2) | columns of table to be interpolated
offset[:] | {0} | Offsets of output signals
extrapolation[1] | {1} | = 0/1/2 constant/last two points/periodic (SAME value for all columns only supported currently)
startTime[1] | {0} | Output = offset for time < startTime (SAME value for all columns only supported currently) [s]

### Modelica definition

    model CombiTableTime2
      "Table look-up with respect to time and linear/perodic extrapolation methods (data from matrix/file)"

      parameter Real table[:, :]=[0, 0; 1, 1] "table matrix (time = first column)";
      parameter String tableName="NoName"
        "table name on file or in function usertab(optional)";
      parameter String fileName="NoName" "file where matrix is stored (optional)";
      parameter Integer columns[:]=2:size(table, 2)
        "columns of table to be interpolated";
      parameter Real offset[:]={0} "Offsets of output signals";
      parameter Integer extrapolation[1](
        min={0},
        max={2}) = {1}
        "= 0/1/2 constant/last two points/periodic (SAME value for all columns only supported currently)"
        ;
      parameter SI.Time startTime[1]={0}
        "Output = offset for time < startTime (SAME value for all columns only supported currently)"
        ;
      extends Modelica.Blocks.Interfaces.MO(final nout=max([size(columns, 1); size(
            offset, 1)]));

      final parameter Real p_offset[nout]=(if size(offset, 1) == 1 then ones(nout)*
          offset[1] else offset);

      final parameter Integer tableID=tableTimeInit(0.0, startTime[1], 0,
          extrapolation[1], tableName, fileName, table, 0);
      final parameter Real t_min=tableTimeTmin(tableID);
      final parameter Real t_max=tableTimeTmax(tableID);

      function tableTimeInit
        input Real timeIn;
        input Real startTime;
        input Integer ipoType;
        input Integer expoType;
        input String tableName;
        input String fileName;
        input Real table[:, :];
        input Integer colWise;
        output Integer tableID;
      external "C" tableID = dymTableTimeIni2(timeIn, startTime, ipoType, expoType
          , tableName, fileName, table, size(table, 1), size(table, 2), colWise);
      end tableTimeInit;

      function tableTimeIpo
        input Integer tableID;
        input Integer icol;
        input Real timeIn;
        output Real value;
      external "C" value = dymTableTimeIpo2(tableID, icol, timeIn);
      end tableTimeIpo;

      function tableTimeTmin
        input Integer tableID;
        output Real Tmin "minimum time value in table";
      external "C" Tmin = dymTableTimeTmin(tableID);
      end tableTimeTmin;

      function tableTimeTmax
        input Integer tableID;
        output Real Tmax "maximum time value in table";
      external "C" Tmax = dymTableTimeTmax(tableID);
      end tableTimeTmax;
    equation
      for i in 1:nout loop
        outPort.signal[i] = p_offset[i] + tableTimeIpo(tableID, columns[i], time);
      end for;
    end CombiTableTime2;

## ModelicaAdditions.Tables.CombiTable1D

Table look-up in one dimension (matrix/file)

### Information

Linear interpolation in one dimension of a table. Via parameter icol it can be defined how many columns of the table are interpolated. If, e.g., icol={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 interpolation is efficient, because a search for a new interpolation starts at the interval used in the last call.
- If the table has only one row, the table value is returned, independent of the value of the input signal.
- If the input signal u is outside of the defined interval, i.e., u > table[size(table,1),1] or u < table[1,1], the corresponding value is also determined by linear interpolation through the last or first two points of the table.
- The grid values (first column) have to be strict monotonically 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 ASCII and binary file format is possible. (the ASCII format is described below). It is most convenient to generate the binary file from Matlab (Matlab 4 storage format), e.g., by command

          save tables.mat tab1 tab2 tab3 -V4

   when the three tables tab1, tab2, tab3 should be used from the model.
3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks.

Table definition methods (1) and (3) do not allocate dynamic memory, and do not access files, whereas method (2) does. Therefore (1) and (3) are suited for hardware-in-the-loop simulation (e.g. with dSpace hardware). When the constant "NO_FILE" is defined, all parts of the source code of method (2) are removed by the C-preprocessor, such that no dynamic memory allocation and no access to files takes place.

If tables are read from an ASCII-file, the file need 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". Afterwards, the corresponding matrix has to be declared with type, name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. Several matrices may be defined one after another.

### Parameters

Name | Default | Description
--- | --- | ---
table[:, :] | [0, 0; 1, 1] | table matrix (grid = first column)
tableName | "NoName" | table name on file or in function usertab(optional)
fileName | "NoName" | file where matrix is stored (optional)
icol[:] | {2} | columns of table to be interpolated

### Modelica definition

    model CombiTable1D "Table look-up in one dimension (matrix/file) "
      parameter Real table[:, :]=[0, 0; 1, 1] "table matrix (grid = first column)";
      parameter String tableName="NoName"
        "table name on file or in function usertab(optional)";
      parameter String fileName="NoName" "file where matrix is stored (optional)";
      parameter Real icol[:]={2} "columns of table to be interpolated";
      extends Modelica.Blocks.Interfaces.MIMOs(final n=size(icol, 1));
    protected
      Real tableID(start=0);
    equation
      when initial() then
        tableID = dymTableInit(1.0, 0.0, tableName, fileName, table, 0.0);
      end when;

      for i in 1:n loop
        y[i] = dymTableIpo1(tableID, icol[i], u[i]);
      end for;
    end CombiTable1D;

## ModelicaAdditions.Tables.CombiTable1Ds

Table look-up in one dimension (matrix/file) with only single input

### Information

Linear interpolation in one dimension of a table. Via parameter icol 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 interpolation is efficient, because a search for a new interpolation starts at the interval used in the last call.
- If the table has only one row, the table value is returned, independent of the value of the input signal.
- If the input signal u is outside of the defined interval, i.e., u > table[size(table,1),1] or u < table[1,1], the corresponding value is also determined by linear interpolation through the last or first two points of the table.
- The grid values (first column) have to be strict monotonically 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 ASCII and binary file format is possible. (the ASCII format is described below). It is most convenient to generate the binary file from Matlab (Matlab 4 storage format), e.g., by command

          save tables.mat tab1 tab2 tab3 -V4

   when the three tables tab1, tab2, tab3 should be used from the model.
3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks.

Table definition methods (1) and (3) do not allocate dynamic memory, and do not access files, whereas method (2) does. Therefore (1) and (3) are suited for hardware-in-the-loop simulation (e.g. with dSpace hardware). When the constant "NO_FILE" is defined, all parts of the source code of method (2) are removed by the C-preprocessor, such that no dynamic memory allocation and no access to files takes place.

If tables are read from an ASCII-file, the file need 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". Afterwards, the corresponding matrix has to be declared with type, name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. Several matrices may be defined one after another.

### Parameters

Name | Default | Description
--- | --- | ---
table[:, :] | [0, 0; 1, 1] | table matrix (grid = first column)
tableName | "NoName" | table name on file or in function usertab(optional)
fileName | "NoName" | file where matrix is stored (optional)
icol[:] | {2} | columns of table to be interpolated

### Modelica definition

    model CombiTable1Ds
      "Table look-up in one dimension (matrix/file) with only single input"

      parameter Real table[:, :]=[0, 0; 1, 1] "table matrix (grid = first column)";
      parameter String tableName="NoName"
        "table name on file or in function usertab(optional)";
      parameter String fileName="NoName" "file where matrix is stored (optional)";
      parameter Real icol[:]={2} "columns of table to be interpolated";
      extends Modelica.Blocks.Interfaces.SIMO(final nout=size(icol, 1));
    protected
      Real tableID(start=0);
    equation
      when initial() then
        tableID = dymTableInit(1.0, 0.0, tableName, fileName, table, 0.0);
      end when;

      for i in 1:nout loop
        y[i] = dymTableIpo1(tableID, icol[i], u);
      end for;
    end CombiTable1Ds;

## ModelicaAdditions.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:

- the first column "table[2:,1]" contains the u[1] grid points,
- the first row "table[1,2:]" contains the u[2] 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 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 interpolation is efficient, because a search for a new interpolation starts at the interval used in the last call.
- If the table has only one element, the table value is returned, independent of the value of the input signal.
- If the input signal u 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 strict monotonically 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 ASCII and binary file format is possible. (the ASCII format is described below). It is most convenient to generate the binary file from Matlab (Matlab 4 storage format), e.g., by command

          save tables.mat tab1 tab2 tab3 -V4

   when the three tables tab1, tab2, tab3 should be used from the model.
3. Statically stored in function "usertab" in file "usertab.c". The matrix is identified by "tableName". Parameter fileName = "NoName" or has only blanks.

Table definition methods (1) and (3) do not allocate dynamic memory, and do not access files, whereas method (2) does. Therefore (1) and (3) are suited for hardware-in-the-loop simulation (e.g. with dSpace hardware). When the constant "NO_FILE" is defined, all parts of the source code of method (2) are removed by the C-preprocessor, such that no dynamic memory allocation and no access to files takes place.

If tables are read from an ASCII-file, the file need 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". Afterwards, the corresponding matrix has to be declared with type, name and actual dimensions. Finally, in successive rows of the file, the elements of the matrix have to be given. Several matrices may be defined one after another.

### Parameters

Name | Default | Description
--- | --- | ---
table[:, :] | [0, 0, 1; 0, 0, 1; 1, 1, 1] | table matrix (grid = first column/first row)
tableName | "NoName" | table name on file or in function usertab(optional)
fileName | "NoName" | file where matrix is stored (optional)

### Modelica definition

    model CombiTable2D "Table look-up in two dimensions (matrix/file) "
      extends Modelica.Blocks.Interfaces.SI2SO;
      parameter Real table[:, :]=[0, 0, 1; 0, 0, 1; 1, 1, 1]
        "table matrix (grid = first column/first row)";
      parameter String tableName="NoName"
        "table name on file or in function usertab(optional)";
      parameter String fileName="NoName" "file where matrix is stored (optional)";
    protected
      Real tableID(start=0);
    equation
      when initial() then
        tableID = dymTableInit(2.0, 0.0, tableName, fileName, table, 0.0);
      end when;

      y = dymTableIpo2(tableID, u1, u2);
    end CombiTable2D;