Lookup tables are a common sight in simulation, taking various forms; 1D, 2D and even 3D, depending on the number of inputs required to determine the output. Each element of a supplied data set is determined relative to inputs; when the lookup table is queried with an input, interpolation is used to determine the output. They can be used for several applications, from varying a control parameter with respect to inputs to substituting for the response of a more complex component.
You’ve likely come across the term “Engine Map” regarding a vehicle’s engine and ECU specifically. Engine maps are lookup tables at heart, where a control parameter vital to the engine’s function is determined with respect to a set of measured input. Maps of this kind can be found in many other similar control applications.
This blog post will be a basic introduction into lookup tables in Dymola, how some of the basic functionality works, what variations are available to the user along with some tips and tricks to use when dealing with them.
Basic functionality in Dymola and Modelica
In the Modelica Standard Library, the package Modelica.Blocks.Tables provides some basic lookup table models. In addition, the Claytex library package Claytex.Blocks.Tables contains more advanced and sophisticated lookup tables equipped with extended functionality. Whilst not wanting to get into the granular aspects of how they work and differ, they both follow the same basic philosophy. Table data/mapping is supplied by the user, which is then compiled by an external C code function into the user PC’s memory. When it is queried with an input, the respective output is then sent back to Dymola.
Figure 1: Example of a Modelica Standard Library lookup table value in external C code.
Different types & dimensions
1D and 2D lookup tables are available in the Modelica Standard Library. Further 3D and ND tables can be found within the Claytex Library.
As both Integer and Boolean values can be represented as Reals, Dymola lookup tables work with Real inputs. This means to create a lookup table of Booleans, then the true and false values can be represented as 1 or 0 Reals. They can then be converted to the required type using a Modelica.Blocks.Math.RealToBoolean or Modelica.Blocks.Math.RealToInteger block. Inputs to the lookup table have to remain Reals, but can be converted from Integer or Booleans using Modelica.Blocks.Math.IntegerToReal or Modelica.Blocks.Math.RealToBoolean.
The actual format lookup table must take, i.e. how the data is ordered, is relatively simple. The first column (and row in 2D tables) should be in ascending order. That means if time is one of the inputs, then it should read 0, 1, 2, 3 etc. Increments between the input points don’t matter, so long as the order is ascending. Another thing to remember when handling 2D tables is the value in the (1,1) location needs to be zero. Without this, the table will not be read, or the data will not copy correctly into the table. When using the GUI to populate, this zero is added by default.
Copy & Paste from Excel
Rather than either having to manually input values into the table or create and update files when you want to change a value in the lookup table, data can be directly copied and pasted into the lookup table from Excel. This makes changing data simple and easy. It should be remembered that this data will then be carried in the model’s text layer, so be careful if directly pasting in large data sets. In that case, using files would be more suitable.
Figure 2: Pasting data copied from Excel is simple, just open the table dialog box and click “Paste Matrix”
Loading data from files
Two file types are supported for usage with lookup tables; text (.txt) and MATLAB (.mat). Using mat files is the simplest, as they can be generated in the correct format from the MATLAB environment, or any environment which supports generation of mat files. MATLAB v4, v6 and v7 files are supported.
Text files on the other hand can be a little more tricky to handle, although they do not need an environment to generate them and be done manually if you so wish. They must follow a specific syntax, with the type (double or float) declared with the name (this is the “tableName” in the table parameters) and dimensions. Data entry is done in row-wise order which means matrices can span multiple lines, not constrained to starting from another line. Number separators can be spaces, tab (\t), comma or semicolons. File must be encoded in ASCII or UTF-8.
Figure 3: Example of how to format text (.txt) files for usage with Modelica lookup tables, taken from Modelica.Blocks.Tables.CombiTable1Ds.
Interpolation & Extrapolation
Interpolation and extrapolation are two very important options to consider when using lookup tables. In Dymola lookup tables, interpolation is known as Smoothness. Both Smoothness and Extrapolation are defined by enumerations, with a selection of possible choices. Without going into excessive detail, interpolation options can range from simple linear, to spline based interpolation of varying types. Extrapolation is more straight forwards, where the user can choose between allowing no extrapolation outside the table boundaries (boundaries are held, in effect limited), extrapolation based on the derivative of the final two points, repeating the table periodically and causing an error if extrapolation is attempted.
Figure 4: Interpolation and Extrapolation options are available via selecting the appropriate enumerations in the drop down menu.
The lookup tables in the Claytex Library have a very useful feature built into them; the ability to apply scaling to the input of the output of the table. This is very useful when conducting SI/non-SI unit conversions into or out of a table, reducing the need for components in your model.
Lookup tables are a simple and easy to use aspect of Dymola which will be familiar to many engineers. Hopefully this introductory guide will help you get up to speed working with lookup tables quicker than before!
Written by: Theodor Ensbury – Senior Project Engineer
Please get in touch if you have any questions or have got a topic in mind that you would like us to write about. You can submit your questions / topics via: Tech Blog Questions / Topic Suggestion.