2.2 UDI Data Structure

UDI supports three basic mathematical objects: matrix , vector , and scalar . The problem is that most computer languages do not directly provide these structures. Traditionally, programmers have used one-dimensional arrays to store vectors and two-dimensional arrays to store matrices. This works fine, and the code even tends to be fairly readable. We first start having problems, however, when we need a matrix of complex numbers. Suddenly, the code becomes a bit more mysterious as the programmer finds ``clever" solutions (i.e. hacks).

UDI provides the user with data abstraction for its three objects. All variables used by UDI are of special type UDI_object" . The following C-language routines create instances of each of the object types:      

void create_matrix(matrix, nrows, ncols, sub_type,
elem_type, val_type)
   UDI_object matrix; /* the matrix object to be created */
   int nrows;         /* number of rows in the matrix */
   int ncols;         /* number of columns in the matrix */
   int sub_type;      /* sub-element type (currently must be ST_UNDEF) */
   int elem_type;     /* element type (see below) */
   int val_type;      /* value type (see below) */

There exist similar routines for creating vector and scalar objects as well.        

void create_vector(vector, num_elem, elem_type, val_type)
   UDI_object vector;
   int num_elem, elem_type, val_type;

void create_scalar(scalar, elem_type, val_type)
   UDI_object scalar;
   int elem_type, val_type;

And there is a single routine for destroying them.    

void kill_object(object)
   UDI_object object;

  
2.2.1 Element type

UDI objects are composed of one or more elements of a specific type, with the following two predefined element types:

element type	description
ELEM_REAL"	a single real datum
ELEM_COMPLEX"	a single complex datum

A future version of UDI may provide routines for defining new element types, with each element possibly containing several data. This would be useful, for example, for a non-periodically sampled time signal where each element would need to have two data, the time and amplitude of the sample.

  
2.2.2 Value type

UDI provides four machine numeric formats for object data.

value type	description
VAL_SHORT"	fixed point (architecture dependent, usually 16-bit)
VAL_LONG"	fixed point (usually 32-bit)
VAL_FLOAT"	floating point (usually 32-bit)
SPMquotVAL_DOUBLE"	floating point (usually 64-bit)

Which value type to use depends on the function and the precision that you require. For many of the functions, only certain value types are allowed. For example, for the trigonometric functions, it only makes sense to use a VAL_FLOAT" or VAL_DOUBLE" value type. Refer to the chapter about the DSP functions for details.

As an example, let's say you wanted to create a vector with a hundred complex floating-point elements:

UDI_object vector;
create_vector(vector, 100, ELEM_COMPLEX, VAL_FLOAT);

Since elements made up of a single data are the most common, there is an alternative way to specify the element and value type. You can call any routine that creates a UDI_object", by passing zero as the element type and passing one of the value types below:

REAL_SHORT"	CMPX_SHORT"
REAL_LONG"	CMPX_LONG"
REAL_FLOAT"	SPMquotCMPX_FLOAT"
SPMquotREAL_DOUBLE"	CMPX_DOUBLE"

We can therefore create the same row vector with the following call:

create_vector(vector, 100, 0, CMPX_FLOAT);