Verilog-A Reference Manual >Chapter 10: System Tasks and I/O Functions
Print version of this Book (PDF file)
prevnext

The $table_model Function

The interpolation function, $table_model(), allows the module to approximate the behavior of a system by interpolating between user-supplied data points. The user provides a dataset of points (xi1, xi2, .., xiN, yi) such that f(xi1, xi2, .., xiN) = yi, where f is the model function and N is the number of independent variables of the model. These data points are stored in a text file and are accessed during the analysis by the Verilog-A module.

The interpolation algorithm then approximates the true model behavior at any point in the domain of the sampled data. Data points outside of the sampled domain will be approximated via extrapolation of the data within the domain. Extrapolated data can be inaccurate and should be avoided.

The Verilog-A algorithm is a piecewise-linear interpolation for the $table_model() function. However, higher-order interpolation algorithms may be provided in a future revision of the language.

The $table_model() system function has the same restrictions as analog operators. That is, it cannot be used inside of if(), case(), or for() statements unless these statements are controlled by genvar-constant expressions.

Syntax
$table_model( table_inputs, table_data_source, table_control_string );

where

table_inputs is an (optionally multi-dimensional) expression. For more information on the table_inputs argument, refer to Table Model Inputs.

table_data_source is either a string indicating the name of the file holding the table data or the name of an array. For more information on the table_data_source argument, refer to Table Data Source.

table_control_string is a two part string. The first character is an integer indicating the degrees of the spline interpolation (either 1 | 2| 3). The second part of the control string consists of one or two characters (either C | L | E) indicating the type of extrapolation mode at the beginning and end of the data. For more information on the table_control_string argument, refer to Table Control String.

The inputs to the $table_model() function are described in more detail in the following sections.

Table Model Inputs

The table_inputs are numerical expressions that are used as the independent model variables for the $table_model() function. They may be any valid expressions that can be assigned to an analog signal.

Table Data Source

The table_data_source argument specifies the source of sample points for the $table_model() function. The sample points may come from two sources: files and arrays. The file source indicates that the sample points be stored in a file, while the array source indicates that the data points are stored in a set of array variables. The user may choose the data source by either providing the file name of a file source or a set of array variables as an argument to the function.

The table is created when the $table_model() system function is called for the first time. Any changes to the table_data_source argument(s) of the $table_model() after the first call are quietly ignored (that is, the table model is not recreated). For a file source, each sample point of the table is represented as a sequence of numbers in the order of Xi1 Xi2 .. XiN Yi, where Xik is the coordinate of the sample point in kth dimension and Yi is the model value at this sample point. Each sample point must be separated by a new line. The numbers in the sequence must be separated by one or more spaces or tabs. Comments may be inserted before or after any sample point; comments must begin with `#' and end with a new line.

The data file must be in text format only. The numbers must be real or integer. The sample points can be stored in the file in any order.

Example

The following example shows the contents of a table model files with two dimensions.

# datafile.tbl
# 2-D table model sample example of the function
# f(x,y) = sqrt(x^2 + y^2)
#
# x y f(x,y)
-2 -2 2.828
-2 -1 2.236
-1 -1 1.414
0 0 0
0 1 1.0
1 1 1.414
1 2 2.236
2 2 2.828

If the source of the data is an array, a set of one-dimensional arrays that contain the data points must be passed to the $table_model() function. The size of these arrays is determined by the number of sample points in the table, M. The data are stored in the arrays such that for the kth dimension of the ith sample point, kth_dim_array_identifier[i] = Xik and such that for the ith sample point output_array_identifier[i] = Yi.

Example

For the previous table model example, the same data would be provided to the function in an array as shown in the following code fragment.

@(initial_step) begin
     x[0]=-2; y[0]=-2; f_table[0]=2.828; // 0th sample point
     x[1]=-2; y[1]=-1; f_table[1]=2.236; // 1st sample point
     x[2]=-1; y[2]=-1; f_table[2]=1.414; // 2nd sample point
     x[3]=-0; y[3]= 0; f_table[3]=0;
     x[4]=-0; y[4]=-1; f_table[4]=1;
     x[5]=-0; y[5]=-1; f_table[5]=1.414;
     x[6]= 1; y[6]= 2; f_table[6]=2.236;
     x[7]= 2; y[7]= 2; f_table[7]=2.828;
end

Table Control String

The control string provides information on how the model should interpolate and extrapolate the table data. The control string consists of sub-strings for each dimension. Each sub-string may contain one character indicating the degree of the spine interpolation and an additional one or two characters indicating the type of extrapolation method to be used.

Table Interpolation Degree

The degree character is an integer between 1 and 3 representing the degrees of splines to be used for the interpolation. If not given, a degree of 1 (linear) is assumed. Table 10-1 shows the possible settings.

Table 10-1. Extrapolation Method Characters
Table Interpolation Character
Interpolation Character Description
1
Linear spline (degree 1)
2
Quadratic spline (degree 2)
3
Cubic spline (degree 3)

Extrapolation Control String

The extrapolation control string is used to control the algorithm to extrapolate beyond the supplied data domain. The string may contain one or two extrapolation method characters. The extrapolation method determines the behavior of the table model when the point to be evaluated is beyond the domain of the user provided sample points. The Clamp extrapolation method, specified with the character C, uses a constant value from the last data point to extend the model.The Linear extrapolation method, specified with the character L, uses piecewise linear interpolation to estimate the requested point. The user may also disable extrapolation by setting the Error extrapolation method using the character E. In this case, an extrapolation error is reported if the $table_model() function is requested to evaluate a point beyond the interpolation region. Table 10-2 summarizes these options.

Table 10-2. Extrapolation Method Characters
Table Extrapolation Character
Extrapolation Character Description
C
Clamp extrapolation
L
Linear extrapolation (default)
E
Error condition

For each dimension of the table, users may use up to two extrapolation method characters to specify the extrapolation method used for each end of the data set. When no extrapolation method character is supplied, the Linear extrapolation method will be used for both ends as default behavior. When a single extrapolation method character is supplied, the specified extrapolation method will be used for both ends of the data set. When two extrapolation method characters are supplied, the first character specifies the extrapolation method used for the end with the lower coordinate value and the second character specifies the extrapolation method for the end with the higher coordinate value. Table 10-3 illustrates some control strings and their interpretation.

Table 10-3. Control String Examples
Control String
Interpretation
"1LE,2EC"
1st dimension linear interpolation, linear extrapolation on left, error on extrapolation to right
2nd dimension quadratic interpolation, error on extrapolation to left, clamp on extrapolation to right
""
Linear interpolation, Linear extrapolation to left and right
,2
1st dimension linear interpolation, 2nd dimension quadratic interpolation, linear extrapolation to left and right
"3,1"
1st dimension cubic interpolation, 2nd dimension linear interpolation, linear extrapolation to left and right

Examples

In the first example, the data from the table defined earlier is contributed across the ports. The data in both dimensions is linearly extrapolated at both ends of the data.

module table_resistor (n1, n2);
electrical n1, n2;
  analog begin
       I(n1, n2) <+ $table_model (V(n1), V(n2), "datafile.tbl", "1L,1L");
  end
endmodule

In the second example, the same information is supplied within the module using the array method.

module user_table(n1, n2);
electrical n1, n2;
real x[0:7], y[0:7], f_table[0:7];
analog begin
     @(initial_step) begin
          x[0]=-2; y[0]=-2; f_table[0]=2.828; // 0th sample point
          x[1]=-2; y[1]=-1; f_table[1]=2.236; // 1st sample point
          x[2]=-1; y[2]=-1; f_table[2]=1.414; // 2nd sample point
          x[3]=-0; y[3]= 0; f_table[3]=0;
          x[4]=-0; y[4]=-1; f_table[4]=1;
          x[5]=-0; y[5]=-1; f_table[5]=1.414;
          x[6]= 1; y[6]= 2; f_table[6]=2.236;
          x[7]= 2; y[7]= 2; f_table[7]=2.828;
     end
     I(a, b) <+ $table_model (V(n1), V(n2), x, y, f_table, "1L,1L");
end
endmodule


prevnext