Interpolation¶

Constructor¶

The constructor function is invoked when an instance of a VectorTable is created (e.g., the declaration of the vector variable in our test case). This constructor function is used to initialize our opaque pointer. Whatever data is required as part of that initialization process should be passed as argument to the constructor function. That same data should be present during instantiation (.e.g, the data argument in our declaration of the vector variable).

The definition of the constructor function is unusual because, unlike our previous examples, it does not include an algorithm section. The algorithm section is normally used to compute the return value of the function. Instead, the constructor function has an external clause. This indicates that the function is implemented in some other language besides Modelica. In this case, that other language is C (as indicated by the "C" following the external keyword). This tells use that the table variable (which is the output of this function and represents the opaque pointer) is returned by a C function named createVectorTable which is passed the contents and size of the ybar variable.

Following the call to createVectorTable is an annotation. This annotation tells the Modelica compiler where to find the source code for this external C function.

The essential point here is that from the point of view of the Modelica compiler, a VectorTable is just an opaque pointer returned by createVectorTable. It is not possible to access the data behind this pointer from Modelica. But this pointer can be passed to other functions, as we shall see in a minute, that are also implemented in C and which do know how to access the data represented by the VectorTable.

Destructor¶

The destructor function is invoked whenever the ExternalObject is no longer needed. This allows the Modelica runtime to clean up any memory consumed by the ExternalObject. An ExternalObject instantiated in a model will generally persist until the end of the simulation. But an ExternalObject declared as a protected variable in a function, for example, may be created and destroyed in the course of a single expression evaluation. For that reason, it is important to make sure that any memory allocated by the ExternalObject is released.

In general, the destructor function is also implemented as an external function. In this case, calling the destructor function from Modelica invokes the C function destroyVectorTable which is passed a VectorTable instance as an argument. Any memory associated with that VectorTable instance should be freed by the call to destructor. Again, we see the same types of annotations used to inform the Modelica compiler where to find the source code for the destoryVectorTable function.

External C Code¶

These external C functions are implemented as follows:

#ifndef _VECTOR_TABLE_C_
#define _VECTOR_TABLE_C_

#include <stdlib.h>
#include "ModelicaUtilities.h"

/*
  Here we define the structure associated
  with our ExternalObject type 'VectorTable'
*/
typedef struct {
  double *x; /* Independent variable values */
  double *y; /* Dependent variable values */
  size_t npoints; /* Number of points in this data */
  size_t lastIndex; /* Cached value of last index */
} VectorTable;

void *
createVectorTable(double *data, size_t np) {
  VectorTable *table = (VectorTable*) malloc(sizeof(VectorTable));
  if (table) {
    /* Allocate memory for data */
    table->x = (double*) malloc(sizeof(double)*np);
    if (table->x) {
      table->y = (double*) malloc(sizeof(double)*np);
      if (table->y) {
        /* Copy data into our local array */
        size_t i;
        for(i=0;i<np;i++) {
          table->x[i] = data[2*i];
          table->y[i] = data[2*i+1];
        }
        /* Initialize the rest of the table object */
        table->npoints = np;
        table->lastIndex = 0;
      }
      else {
        free(table->x);
        free(table);
        table = NULL;
        ModelicaError("Memory allocation error\n");
      }
    }
    else {
      free(table);
      table = NULL;
      ModelicaError("Memory allocation error\n");
    }
  }
  else {
    ModelicaError("Memory allocation error\n");
  }
  return table;
}

void
destroyVectorTable(void *object) {
  VectorTable *table = (VectorTable *)object;
  if (table==NULL) return;
  free(table->x);
  free(table->y);
  free(table);
}

double
interpolateVectorTable(void *object, double x) {
  VectorTable *table = (VectorTable *)object;
  size_t i = table->lastIndex;
  double p;

  ModelicaFormatMessage("Request to compute value of y at %g\n", x);
  if (x<table->x[0])
    ModelicaFormatError("Requested value of x=%g is below the lower bound of %g\n",
      x, table->x[0]);
  if (x>table->x[table->npoints-1])
    ModelicaFormatError("Requested value of x=%g is above the upper bound of %g\n",
      x, table->x[table->npoints-1]);

  while(i<table->npoints-1&&x>table->x[i+1]) i++;
  while(i>0&&x<table->x[i]) i--;

  p = (x-table->x[i])/(table->x[i+1]-table->x[i]);
  table->lastIndex = i;
  return p*table->y[i+1]+(1-p)*table->y[i];
}

#endif

This is not a book on the C programming language so an exhaustive review of this code and exactly how it functions is beyond the scope of the book. But we can summarize the contents of this file as follows.

First, the struct called VectorTable is the data associated wit the VectorTable type in Modelica. This includes not just the interpolation data (in the form of the x and y members), but also the number of data points, npoints, and a cached value for the last used index, lastIndex.

Next, we see the createVectorTable function which allocates an instance of the VectorTable structure and initializes all the data inside it. That instance is then returned to the Modelica runtime. Following the definition of createVectorTable is the definition of destroyVectorTable which effectively undoes what was done by createVectorTable.

Finally, we see the function interpolateVectorTable. This is a C function that is passed an instance of the VectorTable structure and a value for the independent variable and returns the interpolated value for the dependent variable. This function performs almost exactly the same function as the InterpolateVector function presented earlier. The Modelica runtime provides functions like ModelicaFormatError so that external C code can report errors. In the case of interpolateVectorTable, these functions are used to implement the assertions we saw previously in InterpolateVector. The lookup of i is basically the same except that instead of starting from 1 each time, it starts from the value of i found in the last call to interpolateVectorTable.

Interpolation¶

We’ve seen how interpolateVectorTable is defined, but so far we haven’t seen where it is used. We mentioned that performs very much the same role as InterpolateVector, but using a VectorTable object to represent the interpolation data. To invoke interpolateVectorTable from Modelica, we simple need to define a Modelica function as follows:

function InterpolateExternalVector
  "Interpolate a function defined by a vector using an ExternalObject"
  input Real x;
  input VectorTable table;
  output Real y;
  external "C" y = interpolateVectorTable(table, x)
    annotation ...
end InterpolateExternalVector;

We mentioned previously that VectorTable is opaque and that Modelica code cannot access the data contained in the VectorTable. The Modelica function InterpolateExternalVector invokes its C counterpart interpolateVectorTable which can access the interpolation data and, therefore, perform the interpolation.