VectorLibSite Index:OptiVec homeMatrixLib CMATH Download Order Update Support 
VectorLib4. VectorLib Functions and Routines: A Short Overview
4.1 Generation, Initialization and DeAllocation of VectorsWith VectorLib, you may use static arrays (like, for example, float a[100];) as well as dynamically allocated ones (see chapter 2.3). We recommend, however, that you use the more flexible vector types defined by VectorLib, using dynamic allocation. The following functions manage dynamically allocated vectors:
You should always take proper care to deallocate the memory of vectors which are no longer needed. Internally, the allocated vectors are written into a table to keep track of the allocated memory. If you try to free a vector that has never been or is no longer allocated, you get a warning message, and nothing is freed. Performance tips:
The following functions are used to initialize or reinitialize vectors that have already been created:
The following functions generate windows for use in spectral analysis:
Complex vectors may be initialized by these functions:
Back to VectorLib Table of Contents OptiVec home 4.2 Indexoriented Manipulations
Operations performed only on a sampled subset of elements of a vector are provided by the VF_subvector_... family, where the omission mark stands for a suffix denoting the desired operation:
Searching tables for specific values is accomplished by:
Interpolations are performed by:
Back to VectorLib Table of Contents OptiVec home 4.3 DataType InterconversionsThe first thing that has to be said about the floatingpoint datatype interconversions is: do not use them too extensively. Decide which accuracy is appropriate for your application, and then use consistently either the VF_, or the VD_, or the VE_ version of the functions you need. Nevertheless, every data type can be converted into every other, in case it is necessary. Only a few examples are given; the rest should be obvious:
The conversion of floatingpoint numbers into integers is performed by the following functions, differing in the way a possible fractional part is treated:
These operations are treated as mathematical functions and are further described in chapter 4.6.1. Back to VectorLib Table of Contents OptiVec home 4.4 More about Integer ArithmeticsAlthough the rules of integer arithmetics are quite straightforward, it appears appropriate to recall that all integer operations are implicitly performed modulo 2^{n}, where n is the number of bits the numbers are represented with. This means that any result, falling outside the range of the respective data type, is made to fall inside the range by loosing the highest bits. The effect is the same as if as many times 2^{n} had been added to (or subtracted from) the "correct" result as necessary to reach the legal range.For example, in the data type short / SmallInt, the result of the multiplication 5 * 20000 is 31072. The reason for this seemingly wrong negative result is that the "correct" result, 100000, falls outside the range of short numbers which is 32768 <= x <= +32767. short / SmallInt is a 16bit type, so n = 16, and 2^{n} = 65536. In order to make the result fall into the specified range, the processor "subtracts" 2 * 65536 = 131072 from 100000, yielding 31072. Note that overflowing intermediate results cannot be "cured" by any following operation. For example, (5 * 20000) / 4 is not (as one might hope) 25000, but rather 7768. Back to VectorLib Table of Contents OptiVec home 4.5 Basic Functions of Complex VectorsThe following functions are available for the basic treatment of cartesian complex vectors:
The corresponding functions for polar coordinates are:
Back to VectorLib Table of Contents OptiVec home 4.6 Mathematical FunctionsLacking a more wellfounded definition, we denote as "mathematical" all those functions which calculate each single element of a vector from the corresponding element of another vector by a more or less simple mathematical formula:Y_{i} = f( X_{i} ). Except for the "basic arithmetics" functions, they are defined only for the floatingpoint data types. Most of these mathematical functions are vectorized versions of scalar ANSI C or Pascal functions or derived from them. In C/C++, errors are handled by _matherr and _matherrl. In Pascal/Delphi, OptiVec allows the user to control error handling by means of the function V_setFPErrorHandling. In addition to this error handling "by element", the return values of the VectorLib math functions show if all elements have been processed successfully. In C/C++, the return value is of the datatype int, in Pascal/Delphi, it is IntBool. (We do not yet use the newly introduced data type bool for this return value in C/C++, in order to make VectorLib compatible also with older versions of C compilers.) If a math function worked errorfree, the return value is FALSE (0), otherwise it is TRUE (any nonzero number). Back to VectorLib Table of Contents OptiVec home 4.6.1 RoundingSome of the functions converting floatingpoint into integer vectors have already been noted above. The result of these rounding operations may either be left in the original floatingpoint format, or it may be converted into one of the integer types. The following functions store the result in the original floatingpoint format:
The following functions store the result as integers (type int):
The target type may also be any of the other integer data types. A few examples should suffice:
Back to VectorLib Table of Contents OptiVec home 4.6.2 ComparisonsFunctions performing comparisons are generally named VF_cmp... (where further letters and/or numbers specify the type of comparison desired). Every element of a vector can be compared either to 0, or to a constant C, or to the corresponding element of another vector. There are two possibilities: either the comparison is performed with the three possible answers "greater than", "equal to" or "less than". In this case, the results are stored as floatingpoint numbers (0.0, 1.0, or 1.0). Examples are:
The other possibility is to test if one of the following conditions is fulfilled: "greater than", "greater than or equal to", "equal to", "not equal to", "less than", or "less than or equal to". Here, the answers will be "TRUE" or "FALSE" (1.0 or 0.0). Examples are
Alternatively, the indices of the elements for which the answer was "TRUE" may be stored in an indexarray, as in:
While the basic comparison functions check against one boundary, there is a number of functions checking if a vector elements falls into a certain range:
The following functions test if one or more values can be found in a vector:
Back to VectorLib Table of Contents OptiVec home 4.6.3 Direct BitManipulationFor the integer data types, a number of bitwise operations is available, which can be used, e.g., for fast multiplication and divisions by integer powers of 2.
4.6.4 Basic Arithmetics, AccumulationsAs before, only the VF_ function is explicitly named, but the VD_ and VE_ functions exist as well; if it makes sense, the same is true for the complex and for the integertype versions:
Besides these basic operations, several frequentlyused combinations of addition and division have been included, not to forget the Pythagoras formula:
All functions in the right column of the above two sections also exist in an expanded form (with the prefix VFx_...) in which the function is not evaluated for X_{i} itself, but for the expression (a * X_{i} + b), e.g.
The simple algebraic functions exist also in yet another special form, with the result being scaled by some arbitrary factor. This scaled form gets the prefix VFs_:
Other simple operations include:
While, in general, all OptiVec functions are for input and output vectors of the same type, the arithmetic functions exist also for mixedtype operations between the floatingpoint and the integer types. The result is always stored in the floatingpoint type. Examples are:
Similarly, there exists a family of functions for the accumulation of data in either the same type or in higherprecision data types. Some examples are:
Additionally, within the floatingpoint datatypes, you can accumulate two vectors at once:
Back to VectorLib Table of Contents OptiVec home 4.6.5 Geometrical Vector ArithmeticsIn its geometrical interpretation, a vector is a pointer, with its elements representing the coordinates of a point in ndimensional space. There are a few functions for geometrical vector arithmetics, namely
If, on the other hand, two real input vectors X and Y, or one complex input vector XY, define the coordinates of several points in a planar coordinate system, there is a function to rotate these coordinates:
Back to VectorLib Table of Contents OptiVec home 4.6.6 PowersThe following functions raise arbitrary numbers to specified powers. The extrafast "unprotected versions" can be employed in situations where you are absolutely sure that all input elements yield valid results. Due to the much more efficient vectorization permitted by the absence of error checks, the unprotected functions are up to 1.8 times as fast as the protected versions. (This is true from the Pentium CPU on; on older computers, almost nothing is gained.) Be, however, aware of the price you have to pay for this increase in speed: in case of an overflow error, the program will crash without any warning.
The following group of functions is used to raise specified numbers to arbitrary powers:
All of these functions exist also in the expanded "VFx_" form, like VFx_square: Y_{i} = (a * X_{i} + b)² The expanded form of the unprotected functions has the prefix VFux_. The complexnumber equivalents are available as well, both for cartesian and polar coordinates. Additionally, two special cases are covered:
Back to VectorLib Table of Contents OptiVec home 4.6.7 Exponentials and Hyperbolic FunctionsA variety of functions are derived from the exponential function VF_exp (which itself has already been mentioned in the last section).
The vectorized hyperbolic functions are available as:
Back to VectorLib Table of Contents OptiVec home 4.6.8 Logarithms
Again, the cartesiancomplex equivalents exist as well. The polarcomplex versions, however, are special in that their output is always in cartesian coordinates:
As a special form of the decadic logarithm, the Optical Density is made available by a family of functions of which some examples are contained in the following table:
Back to VectorLib Table of Contents OptiVec home 4.6.9 Trigonometric FunctionsThe basic trigonometric functions are available in two variants. The first variant follows the usual rules of error handling for math functions, whereas the second is for situations where you know beforehand that all input arguments will be in the range 2p <= X_{i} <= +2p. If you choose to employ these extrafast reducedrange functions, you really have to be absolutely sure about your input vectors, as these functions will crash without warning in the case of any input number outside the range specified above. The reducedrange functions are available only for the sine and cosine, as all other trigonometric functions need error checking and handling anyway, even in this range.
The following functions yield the squares of the trigonometric functions in a more efficient way than by first calculating the basic functions and squaring afterwards:
A very efficient way to calculate the trigonometric functions for arguments representable as rational multiples of p (PI) is supplied by the trigonometric functions with the suffix "rpi" (meaning "rational multiple of p"). Here, r = p / q, where q is constant and p is given by the input vector elements:
Even more efficient versions use tables to obtain frequentlyused values; these versions are denoted by the suffixes "rpi2" (multiples of p divided by an integer power of 2) and "rpi3" (multiples of p over an integer multiple of 3). Examples are:
Two more special trigonometric functions are:
Vectorized inverse trigonometric functions are available as
Back to VectorLib Table of Contents OptiVec home 4.7 AnalysisThere is a number of functions probing the analytical properties of data arrays:
The complex equivalents of the last group of functions are:
Sums, products, etc. are available by functions grouped as statistical building blocks and summarized in chapter 4.9. To determine the center of gravity of a vector, you have the choice between the following two functions:
Back to VectorLib Table of Contents OptiVec home 4.8 Signal Processing:
The following list of functions is available for signal processing applications:

VF_FFTtoC  forward Fast Fourier Transform (FFT) of a real vector; the result is a cartesian complex vector 
VF_FFT  forward and backward FFT of a real vector; the result of the forward FFT is packed into a real vector of the same size as the input vector 
VCF_FFT  forward and backward FFT of a complex vector 
MF_Rows_FFT  FFT along the rows of a matrix; this function may be used for batchprocessing of several vectors of identical size, stored as the rows of a matrix 
MF_Cols_FFT  FFT along the columns of a matrix; this function may be used for batchprocessing of several vectors of identical size, stored as the columns of a matrix 
VF_convolve  convolution with a given response function 
VF_deconvolve  deconvolution, assuming a given response function 
VF_filter  spectral filtering 
VF_spectrum  spectral analysis 
VF_autocorr  autocorrelation function of a data array 
VF_xcorr  crosscorrelation function of two arrays 
VF_setRspEdit  set editing threshold for the filter in convolutions and deconvolutions (decides over the treatment of "lost" frequencies) 
VF_getRspEdit  retrieve the current editing threshold 
Although they do not use Fourier transform methods, the functions VF_biquad (biquadratic audio filtering) and VF_smooth (crude form of frequency filtering which removes highfrequency noise) should be mentioned here.
Back to VectorLib Table of Contents OptiVec home
VF_sum  sum of all elements 
VI_fsum  sum of all elements of an integer vector, accumulated as a floating point number in double or extended precision 
VF_prod  product of all elements 
VF_ssq  sumofsquares of all elements 
VF_sumabs  sum of absolute values of all elements 
VF_rms  rootofthemeansquare of all elements 
VF_runsum  running sum 
VF_runprod  running product 
VF_sumdevC  sum over the deviations from a preset constant, sum( X_{i}C ) 
VF_sumdevV  sum over the deviations from another vector, sum( X_{i}Y_{i} ) 
VF_avdevC  average deviation from a preset constant, 1/N * sum( X_{i}C ) 
VF_avdevV  average deviation from another vector, 1 / N * sum( X_{i}Y_{i} ) 
VF_ssqdevC  sumofsquares of the deviations from a preset constant, sum( (X_{i}  C)² ) 
VF_ssqdevV  sumofsquares of the deviations from another vector, sum( (X_{i}  Y_{i})² ) 
VF_chi2  chisquare merit function 
VF_chiabs  "robust" merit function, similar to VF_chi2, but based on absolute instead of squared deviations 
VF_mean  equallyweighted mean (or average) of all elements 
VF_meanwW  "mean with weights" of all elements 
VF_meanabs  equallyweighted mean (or average) of the absolute values of all elements 
VF_selected_mean  averages only those vector elements which fall into a specified range, thus allowing to exclude outlier points from the calculation of the mean 
VF_varianceC  variance of a distribution with respect to a preset constant value 
VF_varianceCwW  the same with nonequal weighting 
VF_varianceV  variance of one distribution with respect to another 
VF_varianceVwW  the same with nonequal weighting 
VF_meanvar  mean and variance of a distribution simultaneously 
VF_meanvarwW  the same with nonequal weighting 
VF_median  median of a distribution 
VF_corrcoeff  linear correlation coefficient of two distributions 
VF_distribution  bins data into a discrete onedimensional distribution function 
VF_min_max_mean_stddev  simultaneous calculation of the minimum, maximum, mean, and standard deviation of a onedimensional distribution 
Back to VectorLib Table of Contents OptiVec home
A detailed description of the various datafitting concepts is given elsewhere. Therefore, at this place, the available XY fitting functions are only summarized in the following table:
VF_linregress  equallyweighted linear regression on XY data 
VF_linregresswW  the same with nonequal weighting 
VF_polyfit  fitting of one XY data set to a polynomial 
VF_polyfitwW  the same for nonequal datapoint weighting 
VF_linfit  fitting of one XY data set to an arbitrary function linear in its parameters 
VF_linfitwW  the same for nonequal datapoint weighting 
VF_setLinfitNeglect  set threshold to neglect (i.e. set equal to zero) a fitting parameter A[i], if its significance is smaller than the threshold 
VF_getLinfitNeglect  retrieve current significance threshold 
VF_nonlinfit  fitting of one XY data set to an arbitrary, possibly nonlinear function 
VF_nonlinfitwW  the same for nonequal datapoint weighting 
VF_multiLinfit  fitting of multiple XY data sets to one common linear function 
VF_multiLinfitwW  the same for nonequal datapoint weighting 
VF_multiNonlinfit  fitting of multiple XY data sets to one common nonlinear function 
VF_multiNonlinfitwW  the same for nonequal datapoint weighting 
Back to VectorLib Table of Contents OptiVec home
VF_cprint  print the elements of a vector to the screen (or "console"  hence the "c" in the name) into the current text window, automatically detecting its height and width. After printing one page, the user is prompted to continue. (Only for DOS) 
VF_print  is similar to VF_cprint in that the output is directed to the screen, but there is no automatic detection of the screen data; a default linewidth of 80 characters is assumed, and no division into pages is made. (Only for DOS and EasyWin) 
VF_fprint  print a vector to a stream. 
VF_write  write data in ASCII format in a stream 
VF_read  read a vector from an ASCII file 
VF_nwrite  write n vectors of the same data type as the columns of a table into a stream 
VF_nread  read the columns of a table into n vectors of the same type 
VF_store  store data in binary format 
VF_recall  retrieve data in binary format 
VF_setWriteFormat  define a certain number format 
VF_setWriteSeparate  define a separation string between successive elements, written by VF_write 
VF_setNWriteSeparate  define a separation string between the columns written by VF_nwrite 
V_setRadix  define a radix different from the standard of 10 for the wholenumber variants of the V..read functions 
Back to VectorLib Table of Contents OptiVec home
V_initPlot  initialize VectorLib graphics functions (both Windows and DOS). For Windows, no shutdown is needed at the end, since the Windows graphics functions always remain accessible. V_initPlot automatically reserves a part of the screen for plotting operations. This part comprises about 2/3 of the screen on the right side. Above, one line is left for a heading. Below, a few lines are left empty. To change this default plotting region, call V_setPlotRegion after V_initPlot. 
V_initGraph  simultaneously initialize Borland's graphics interface and VectorLibplotting functions (DOS only). 
V_initPrint  initialize VectorLib graphics functions and direct them to a printer (Windows only). By default, one whole page is reserved for plotting. In order to change this, call V_setPlotRegion after V_initPrint. 
V_setPlotRegion  set a plotting region different from the default 
VF_xyAutoPlot  display an automaticallyscaled plot of an XY vector pair 
VF_yAutoPlot  plot a single Yvector, using the index as Xaxis 
VF_xy2AutoPlot  plot two XY pairs at once, scaling the axes in such a way that both vectors fit into the same coordinate system 
VF_y2AutoPlot  the same for two Yvectors, plotted against their indices 
VF_xyDataPlot  plot one additional set of XY data 
VF_yDataPlot  plot one additional Y vector over its index 
VCF_autoPlot  plot one cartesian complex vector 
VCF_2AutoPlot  plot two cartesian complex vectors simultaneously 
VCF_dataPlot  plot one additional cartesian complex vector 
V_continuePlot  go back to the viewport of the last plot and restore its scalings 
V_getCoordSystem  get a copy of the scalings and position of the current coordinate system 
V_setCoordSystem  restore the scalings and position of a coordinate system; these must have been stored previously, using V_getCoordSystem 
Continue with chapter 5. Error Handling
Back to VectorLib Table of Contents
OptiVec home
Copyright © 19982012 OptiCode  Dr. Martin Sander Software Development