OptiVec Version 3 for C/C++ and for Pascal/Delphi
OptiCode Dr. Martin Sander Software Development Steinachstr. 9A D-69198 Schriesheim Germany http://www.optivec.com e-mail: support@optivec.com or sales@optivec.com	Part I. A: Handbook

This HANDBOOK describes the basic principles of the OptiVec libraries and gives an overview over VectorLib, the first part of OptiVec. The new object-oriented interface, VecObj, is described in chapter 3. The other parts have their own descriptions in separate files, see MATRIX.HTM and CMATH.HTM.
Chapter 1.2 of this Handbook contains the licence terms for the Shareware version, Chapter 1.3 for the Registered version.
 
OptiCode™ and OptiVec™ are trademarks of Dr. Martin Sander Software Dev. Other brand and product names mentioned in this handbook for identification purposes are trademarks or registered trademarks of their respective holders.
 

German-speaking users: Um die Kosten für das Herunterladen der Shareware-Version über das Internet für alle so gering wie möglich zu halten, enthält diese nur die englische Dokumentation. Sie finden die deutsche Beschreibung separat unter http://www.optivec.com/download/OVDOCD.ZIP.

Contents

---

1. Introduction

OptiVec offers a powerful set of routines for numerically demanding applications, making the philosophy of vectorized programming available for C/C++ and Pascal/Delphi languages. It serves to overcome the limitations of loop management of conventional compilers – which proved to be one of the largest obstacles in the programmer's way towards efficient coding for scientific and data analysis applications.

In comparison to the old vector language APL, OptiVec has the advantage of being incorporated into the modern and versatile languages C/C++ and Pascal/Delphi. Recent versions of C++ and Fortran do already offer some sort of vector processing, by virtue of iterator classes using templates (C++) and field functions (Fortran90). Both of these, however, are basically a convenient means of letting the compiler write the loop for you and then compile it to the usual inefficient code. The same is true for most implementations of the popular BLAS (Basic Linear Algebra Subroutine) libraries. In comparison to these approaches, OptiVec is superior mainly with respect to execution speed – on the average by a factor of 2-3, in some cases even up to 8. The performance is no longer limited by the quality of your compiler, but rather by the real speed of the processor!

There is a certain overlap in the range of functions offered by OptiVec and by BLAS, LINPACK, and other libraries and source-code collections. However, the latter must be compiled, and, consequently, their performance is determined mainly by the quality of the compiler chosen. To the best of our knowledge, OptiVec, was the first product on the market offering a comprehensive vectorized-functions library realized in a true Assembler implementation.

• All operators and mathematical functions of C/C++ and Pascal/Delphi are implemented in vectorized form; additionally many more mathematical functions are included which normally would have to be calculated by more or less complicated combinations of existing functions. Not only the execution speed, but also the accuracy of the results is greatly improved.
• A wide range of optimized matrix functions like matrix arithmetics, algebra, decompositions, data fitting, etc. is offered by MatrixLib.
  TensorLib is planned as a future extension of these concepts for general multidimensional arrays.
• Fast Fourier Transform techniques (both one- and two-dimensional) allow for efficient convolutions, correlation analyses, spectral filtering, and so on.
• Building blocks for statistical data analysis are supplied.
• Derivatives, integrals, interpolation schemes are included.
• Graphical representation of data offers a convenient way of monitoring the results of vectorized calculations.
• Each function exists for every data type for which this is reasonable. The data type is signalled by the prefix of the function name. No implicit name mangling or other specific C++ features are used in the C/C++ version, which makes OptiVec usable in plain-C as well as in C++ programs. Moreover, the names and the syntax of nearly all functions are the same in C/C++ and Pascal/Delphi languages.
• The input and output vectors/matrices of VectorLib and MatrixLib routines may be of variable size and it is possible to process only a part (e.g., the first 100 elements, or every 10th element) of a vector, which is another important advantage over other approaches, where only whole arrays are processed.
• A new object-oriented interface for C++, named VecObj, encapsulates all vector functions, offering even easier use and increased memory safety.
• Using OptiVec routines instead of loops can make your source code much more compact and far better readable.
• Besides the vectorized complex-number functions, CMATH is included. This is a comprehensive library of complex operations and functions, both in cartesian and polar coordinates. In comparison to complex class libraries shipped with C++ compilers and to the unit Complex of Delphi, CMATH is generally much faster, more complete, more accurate and numerically stable.

The wide range of routines and functions covered by OptiVec, the high numerical efficiency and increased ease of programming make this package a powerful programming tool for scientific and data analysis applications, competing with (and often beating) many high-priced integrated systems, but imbedded into your favourite programming language.

This documentation describes the OptiVec implementations for

• Borland C++ (all versions of Borland C++ Builder and Borland C++, version 4.0 or higher) for 32-bit Windows, DOS, or Windows 3.x.
• Microsoft Visual C++ (version 5.0 or higher) for 32-bit Windows on PC platforms.
• Borland Delphi, versions 4 through 7 on 32-bit Windows
• Borland (Turbo) Pascal 7.0 for DOS

1. Shareware version for Borland C++:
   Depending on your choice when ordering or downloading, you have got either of the following three library versions:
   • Memory model FLAT for 32-bit Windows, statically linked runtime library
   • LARGE for DOS, or
   • LARGE for Windows 3.x.
   All of them require, at least, a 386 computer equipped with a 387 coprocessor. This means: no emulation, no 486SX, but preferably 486DX, Pentium or higher. As of now, the P6 and P7 libraries (for Pentium III, Pentium IV or higher) are included only with the registered version.

2. Registered version for Borland C++:
   The full (registered) version for Borland C++ contains libraries for all memory models of DOS, 16-bit Windows and 32-bit Windows. These libraries, in turn, are shipped in five versions: one for P7 (Pentium IV or higher) computer, the second for P6 (Pentium III or higher), the third for 486DX and Pentium, the fourth for 386 with 387, and – still available – the fifth for 286 with or without coprocessor, i.e. with emulation. The P6 and P7 versions should be used only with BC++ 5.x, BCB 5 or higher.

3. Microsoft Visual C++:
   The Shareware version has 486DX/Pentium libraries for "single-thread debug" and "multi-thread debug". The full (registered) version for Microsoft Visual C++ contains additional libraries for "multi-thread DLL debug" and the three corresponding release libraries, in three versions for P7 (Pentium IV or higher), for P6 (Pentium III or higher), and for 486/Pentium+. There is no actual debug information enclosed in the OptiVec "debug" libraries, but they have to be used with the debug libraries of Visual C++.

4. Borland Delphi: The Shareware version requires, at least, a 386 computer equipped with a 387 coprocessor. This means: no emulation, no 486SX, but preferrably 486DX, Pentium or higher. The Registered version has separately optimized libraries for P7 (Pentium IV or higher), for P6 (Pentium III or higher), for 486/Pentium, and for 386+387.

5. Borland Pascal 7.0: The Shareware version is for the real-mode DOS target and requires, at least, a 386 computer equipped with a 387 coprocessor. The registered version of OptiVec for Borland Pascal has separate units for 486/Pentium and 386+387, both for real-mode and protected-mode DOS. 286 fossils are no longer supported.

Back to Table of Contents

1.1 Why Vectorized Programming Pays Off on the PC

Vectorization has always been the magic formula for supercomputers with their multi-processor parallel architectures. On these architectures, one tries to spread the computational effort equally over the available processors, thus maximizing execution speed. The so-called "divide and conquer" algorithms break down more complicated numerical tasks into small loops over array elements. Sophisticated compilers then find out the most efficient way how to distribute the array elements among the processors. Many supercomputer compilers also come with a large set of pre-defined proprietary vector and matrix functions for many basic tasks. These vectorized functions offer the best way to achieve maximum throughput.

Obviously, the massive parallel processing of, say, a Cray is not possible on most PCs with their one and only CPU. (Even high-end workstations feature still modest 2 or 4-CPU configurations.) Consequently, at first sight, it might seem useless to apply the principle of vectorized programming to the PC. Actually, however, there are many vector-specific optimizations possible, even for computers with only one CPU. Most of these optimizations are not available to present compilers. Rather, one has to go down to the machine-code level. Hand-optimized, Assembler-written vector functions outperform compiled loops by a factor of two to three, on the average. This means that vectorization, properly done, is indeed worth the effort, also for PC programs.

Here are the most important optimization strategies, employed in OptiVec to boost the performance:

Prefetch of chunks of vector elements
Beginning with the Pentium III processor, Intel introduced the very useful feature of explicit memory prefetch. With these commands, it is possible to "tell" the processor to fetch data from memory sufficiently in advance, so that no time is waisted waiting for them when they are actually needed.

Cache control
The Pentium III+ processors offer the possibility to mark data as "temporal" (will be used again) or "non-temporal" (used only once), while they are fetched or stored. In OptiVec functions, it is assumed that input vectors (and matrices) will not be used again, whereas the output vectors are likely to become the input for some ensuing procedure. Consequently, the cache is bypassed while loading input data, but the output data are written into the cache. Of course, this approach breaks down if the vectors or matrices become too large to fit into the cache. For these cases, a large-vector version of the OptiVec libraries is available which bypasses the cache also while writing the output vectors. For simple arithmetic functions, up to 20% in speed are gained as compared to the small-and-medium-size version. On the other hand, as this large-vector version effectively switches the cache off, a drastic performance penalty (up to a factor of three or four!) will result, if it is used for smaller systems. For the same reason, you should carefully check if your problem could perhaps be split up into smaller vectors, before resorting to the large-vector version. This would allow to achieve the much higher performance resulting from efficient data caching.

Use of SIMD commands
You might wonder why this strategy is not listed first. The SSE or "Streaming Single-Instruction-Multiple-Data Extensions" of Pentium III and Pentium 4 provide explicit support for vectorized programming with floating-point data in float / single or double precision (the latter only for Pentium 4). At first sight, therefore, they should revolutionize vector programming. Given today's processor and data bus speeds, however, many of the simple arithmetic operations have become data transfer limited, and the use of SIMD commands does not make the large difference (with respect to well-written FPU code) it could make otherwise. In most cases, the advantage of treating four floats in a single command melts down to a 20-30% increase in speed (which is not that bad, anyway!). For more complicated operations, on the other hand, SIMD commands often cannot be employed, either because conditional branches have to be taken for each vector element individually, or because the "extra" accuracy and range, available by traditional FPU commands (with their internal extended accuracy), allows to simplify algorithms so much that the FPU code is still faster. As a consequence, we use SIMD commands only where a real speed gain is possible without affecting the accuracy.

Preload of floating-point constants
Floating-point constants, employed in the evaluation of mathematical functions, are loaded onto the floating-point number stack outside of the actual loop and stay as long as they are needed. This saves a large amount of loading/unloading operations which are necessary if a mathematical function is called for each element of a vector separately.

Full FPU stack usage
Where necessary, all eight coprocessor are employed. (For present compilers, it is already an excellent achievement to master the bookkeeping for only four coprocessor registers.)

Superscalar scheduling
By careful "pairing" of commands whose results do not depend upon each other, the two integer pipes and the two fadd/fmul units of the Pentium/PentiumXX are used as efficiently as possible.
In most instances, computers equipped with 386/387 or 486DX CPUs just will not care about these optimizations which they cannot profit from. In those cases, however, where the performance on these older CPUs suffers significantly from the Pentium-optimized scheduling, it is applied only in the "4" version of OptiVec (back-compatible to 486DX), but not in the "3" version (back-compatible to 386/387).

Loop-unrolling
Where optimum pairing of commands cannot be achieved for single elements, vectors are often processed in chunks of two, four, or even more elements. This allows to fully exploit the parallel-processing capabilities of the Pentium and its successors. Moreover, the relative amount of time spent for loop management is significantly reduced. In connection with data-prefetching, described above, the depth of the unrolled loops is most often adapted to the cache line size of 32 bytes.

Simplified addressing
The addressing of vector elements is still a major source of inefficiency with present compilers. Switching forth and back between input and output vectors, a large number of redundant addressing operations is performed. The strict (and easy!) definitions of all OptiVec functions allow to reduce these operations to a minimum.

Replacement of floating-point by integer commands
For any operations with floating-point numbers that can also be performed using integer commands (like copying, swapping, or comparing to preset values), the faster method is consistently employed.

Strict precision control
C compilers convert a float into a double – Borland Pascal/Delphi even into extended – before passing it to a mathematical function. This approach was useful at times when disk memory was too great a problem to include separate functions for each data type in the .LIB files, but it is simply inefficient on modern PCs. Consequently, no such implicit conversions are present in OptiVec routines. Here, a function of a float is calculated to float (i.e. single) precision, wasting no time for the calculation of more digits than necessary – which would be discarded anyway. Additionally, you can call V_setFPAccuracy( 1 ); to actively switch the FPU to single precision, if that is enough for a given application. Thereby, execution can be significantly sped up from Pentium CPUs on. For details and precautions, see V_setFPAccuracy.

All-inline coding
All external function calls are eliminated from the inner loops of the vector processing. This saves the execution time necessary for the "call / ret" pairs and for loading the parameters onto the stack.

Cache-line matching of local variables
The Level-1 cache of the Pentium and its presently available successors is organized in lines of 32 bytes each. Many OptiVec functions need double-precision or extended-precision real local variables on the stack (mainly for integer/floating-point conversions or for range checking). Present compilers align the stack on 4-byte boundaries, which means there is a 1-in-4 chance that the 8 bytes of a double or the 10 bytes of an extended, stored on the stack, will cross a 32-byte boundary. This, in turn, would lead to a cache line-break penalty, deteriorating the performance. Consequently, those OptiVec functions where this is an issue, use special procedures to align their local variables on 8-byte (for doubles) or 16-byte boundaries (for extendeds).

Unprotected and reduced-range functions
OptiVec offers alternative forms of some mathematical functions, where you have the choice between the fully protected variant with error handling and another, unprotected variant without. In the case of the integer power functions, for example, the absence of error checking allows the unprotected versions to be vectorized much more efficiently. Similarly, the sine and cosine functions can be coded more efficiently for arguments that the user can guarantee to lie in the range -2p and +2p. In these special cases, the execution time may be reduced by up to 40%, depending on the hardware environment. This increased speed has always to be balanced against the increased risk, though: If any input element outside the valid range is encountered, the unprotected and reduced-range functions will crash without warning.

Multithread support
All the above being said about single-CPU PCs, there are high-end workstations and servers on the market, equipped with 2 or 4 PentiumXX chips. While multi-tasking and multi-threading is possible also on single-CPU PCs, multi-processor configurations allow the operating system to distribute threads among the available processors, doubling or quadrupling the overall performance. For that, any functions running in parallel must be prevented from interfering with each other through read/write operations on global variables. With very few exceptions (namely the plotting functions, which have to use global variables to store the current window and coordinate system settings), all other OptiVec functions may run in parallel. OptiVec functions do not initiate threads themselves, though, as the overhead involved in multi-threading would significantly affect the performance on single-CPU machines. If you have a multi-CPU computer, you have to explicitly launch the threads you wish to run in parallel. For example, one thread might take the lower half of the vector(s) you wish to process, while a second thread takes the upper half – until a point is reached, where both must be combined.
Be extremely careful with multi-threading, if you are using the P6 or P7 versions of OptiVec: The earlier releases of 32-bit Windows do not save the XMM registers (employed in the SIMD commands) during task switches.

Back to Table of Contents

1.2 Licence Terms for the Shareware Version

Back to Table of Contents

1.3 Registered Versions

1.3.1 Registered Versions: Ordering

Purchasing the full (registered) version gives you the right to use it on as many computers at a time as the number of units you bought.

The right to distribute applications employing functions of OptiVec is included in the commercial-version licence. No run-time licence are needed for your customers! Corporate site and world-wide licences are available upon request.

The full versions (both the commercial and the educational editions) of OptiVec

• support all memory models of 32-bit Windows, Windows 3.x, and DOS (Borland C++)
  
• single-thread, multi-thread, multi-thread DLL debug and release (Microsoft Visual C++)
  
• Delphi 4 through 7 (Borland Delphi)
  
• the real-mode DOS and DPMI targets (Borland Pascal 7.0)
  
• Borland C++ and Pascal only:
  have individually optimized libraries for each degree of processor backward-compatibility:
  P7 (requiring Pentium 4; 32-bit libraries only)
  P6 (requiring Pentium III; 32-bit libraries only)
  486DX/Pentium+ (optimized for Pentium II)
  386+ (387 coprocessor required; only for Borland compilers)
  286+ (no coprocessor required; C/C++ 16-bit only).
  
• (C/C++ versions only:) come with free printed documentation (which, however, is updated much less frequently than the electronic documentation).
  
• entitle you to two years of free updates (by downloading from our web site)
  
• can be ordered the following ways:
  a) International orders (credit-card or US cheque) by Internet, mail, FAX, or phone
  b) Orders within the European Union (pre-paid or upon invoice)

a) International Orders: Pricing

OptiVec for Borland C/C++,  Microsoft Visual C++,  or Borland Delphi
(CD-ROM, printed handbook available for the C/C++ versions in English or German)

CMATH for Borland C/C++,  Microsoft Visual C++,  or Borland Delphi separately
(CD-ROM, manual in English)

OptiVec for Borland (Turbo) Pascal

CMATH for Borland (Turbo) Pascal separately

International: Ordering Options

SWREG:
When ordering online through SWREG, please use the product-specific links below:
OptiVec for C/C++
OptiVec for Pascal/Delphi
Please choose the exact version and delivery options in the simple pulldown menu on the respective page.

ShareIt:
When ordering online through ShareIt, please use the product-specific links below:
OptiVec for Borland C/C++ (English)
OptiVec für Borland C/C++ (Deutsch)
CMATH for Borland C/C++
OptiVec for Microsoft Visual C++
CMATH for Microsoft Visual C++
OptiVec for Borland Delphi
CMATH for Borland Delphi
OptiVec for Borland (Turbo) Pascal
CMATH for Borland (Turbo) Pascal

You may also order by e-mail to register@shareit.com.
US customers can also contact ShareIt! by telephone 1-724-850-8186 or FAX 1-724-850-8189 (only for orders, please).
Note the program No.: 

	commercial	educational
OptiVec for Borland C/C++ (English)	101557	102654
OptiVec für Borland C/C++ (Deutsch)	101556	149813
CMATH for Borland C/C++	101353	102655
OptiVec for Microsoft Visual C++	103421	149811
CMATH for Microsoft Visual C++	103422	103441
OptiVec for Borland (Turbo) Pascal	103423
CMATH for Borland (Turbo) Pascal	103424
OptiVec for Borland Delphi	103443	103859
CMATH for Borland Delphi	103844	103860

b) Orders in the European Union

OptiVec for Borland C/C++,  Microsoft Visual C++,  or Borland Delphi
(CD-ROM, printed handbook available for the C/C++ versions in English or German)

CMATH for Borland C/C++,  Microsoft Visual C++,  or Borland Delphi separately
(CD-ROM, manual in English)

OptiVec for Borland (Turbo) Pascal

CMATH for Borland (Turbo) Pascal separately

If you have a European VAT ID, or if you order from outside the European Union, you are exempt from German VAT, and it will be deduced from your bill, but you may have to pay your local VAT and/or import duties according to local laws.

Please send a print-out of this order form to

OptiCode – Dr. Martin Sander Software Dev.
Steinachstr. 9A
D-69198 Schriesheim
Germany

FAX +49 - 6203 - 601 733

For any other questions related to ordering OptiVec, please contact us at: sales@optivec.com

Back to Table of Contents

1.3.2 License Terms for the Registered version

Back to Table of Contents

1.4 Getting Started

1. In order to use OptiVec, you need an already installed copy of your C/C++, Delphi, or Pascal compiler. Install OptiVec by executing INSTALL.EXE from the root directory of the installation disk or CD-ROM. Normally, OptiVec will be installed into a directory named "OPTIVEC". This directory holds the documentation.
2. Include the OptiVec lib and include (C/C++) or units (Pascal/Delphi) subdirectories into the search path.
3. a) C/C++:
   Assuming your OptiVec directory is C:\OPTIVEC, add
   C:\OPTIVEC\LIB to the library search path and
   C:\OPTIVEC\INCLUDE to the include-file search path of the IDE (and of the configuration file TURBOC.CFG and BCC32.CFG in case you are using Borland's command-line compilers).
    
   b) Pascal/Delphi, Shareware version:
   Pascal: The units will be installed into the directory OPTIVEC\UNITS.
   Delphi: The units (.DCU files) will be installed into the directory OPTIVEC\LIB.
    
   c) Pascal/Delphi, Registered version:
   Pascal: The units for 386+387 will be installed into the directory OPTIVEC\UNITS.
   The additional units for 486/Pentium are contained in the file UNITS4.ZIP and are not automatically installed. If you wish to use them, manually create the subdirectory OPTIVEC\UNITS4 and unzip the file mentioned into it.
   Delphi: The installation routine you have to execute is named after the target Delphi version: INSTALL4.EXE, INSTALL5.EXE, INSTALL6.EXE, etc. The units (.DCU files) for 486 will be installed into OPTIVEC\LIB3, those for 486 into OPTIVEC\LIB4, those for Pentium III+ into OPTIVEC\LIB6, and the large-vector version of the latter into OPTIVEC\LIB6L. Likewise, the units for Pentium 4 go into OPTIVEC\LIB7 and OPTIVEC\LIB7L.
4. Choose the desired platform, target, and configuration:
   1. Borland C++:
      Choose the desired platform (DOS, Windows3.x, or Win32) and memory model. Select the required library from the following table (add the suffix .LIB) and add it to your project.
      The Shareware versions contain only libraries for either DOS-LARGE, Windows-LARGE, or Win32.
      Borland C++ 16-bit models only:
      If you wish to use MatrixLib functions, you must additionally include another library in your project list, whose name is derived from the names in the table by replacing the leading "V" by "M". For example, for DOS-LARGE, 386, you would need VCL3.LIB and MCL3.LIB.
      Likewise, if you wish to use CMATH functions, you have to add the CMATH library, whereby the letter "V" is replaced by "CMATH". For the above example, this would be CMATHL3.LIB.
       

      Platform	Memory Model	Required Processor
      		286 386+387 486DX/Pentium Pentium III Pentium 4
      DOS	TINY	VCS2 VCS3 VCS4
      DOS	SMALL	VCS2 VCS3 VCS4
      DOS	MEDIUM	VCM2 VCM3 VCM4
      DOS	COMPACT	VCC2 VCC3 VCC4
      DOS	LARGE	VCL2 VCL3 VCL4
      DOS	HUGE	VCH2 VCH3 VCH4
      Windows	SMALL	VCS2W VCS3W VCS4W
      Windows	MEDIUM	VCM2W VCM3W VCM4W
      Windows	COMPACT	VCC2W VCC3W VCC4W
      Windows	LARGE	VCL2W VCL3W VCL4W
      32-bit Windows static run-time library dynamic run-time library	(FLAT) GUI or Console	VCF3W VCF3WD   VCF4W VCF4WD   VCF6W VCF6WD   VCF7W VCF7WD
      32-bit Windows static run-time library dynamic run-time library	(FLAT) Large-Vector version	VCF6L VCF6LD   VCF7L VCF7LD

       
   2. Visual C++: Choose the target and configuration and add the corresponding OptiVec library to your project, according to the following table. Note that the Shareware version contains only the 486DX/Pentium libraries for single-thread debug and multi-thread debug.
       

      Target	Configuration	486/Pentium	Pentium III	Pentium III, Large-vector version	Pentium III	Pentium 4, Large-vector
      single-thread	debug	OVVCSD.LIB	OVVCSD6.LIB	OVVCLSD6.LIB	OVVCSD7.LIB	OVVCLSD7.LIB
      single-thread	release	OVVCSR.LIB	OVVCSR6.LIB	OVVCLSR6.LIB	OVVCSR7.LIB	OVVCLSR7.LIB
      multi-thread	debug	OVVCMTD.LIB	OVVCMTD6.LIB	OVVCLTD6.LIB	OVVCMTD7.LIB	OVVCLTD7.LIB
      multi-thread	release	OVVCMTR.LIB	OVVCMTR6.LIB	OVVCLTR6.LIB	OVVCMTR7.LIB	OVVCLTR7.LIB
      multi-thread DLL	debug	OVVCMDD.LIB	OVVCMDD6.LIB	OVVCLDD6.LIB	OVVCMDD7.LIB	OVVCLDD7.LIB
      multi-thread DLL	release	OVVCMDR.LIB	OVVCMDR6.LIB	OVVCLDR6.LIB	OVVCMDR7.LIB	OVVCLDR7.LIB

       
      In order to allow OptiVec to be used in applications both with and without MFC, it calls the Windows API only directly, not via MFC. However, if you use MFC (either as a static library or as a DLL), Visual C++ does not automatically link the import library, user32.lib. You have to explicitly do this yourself: The line, Project / Settings / Linker / Object and Library Modules must contain user32.lib. Otherwise you would get the linker error "error LNK2001: Unresolved external symbol __imp__MessageBoxA@??".
       
   3. Borland Pascal:
      Choose the target DOS real mode or (for the registered version only) DOS protected-mode.
      If you can, use the protected-mode version of the compiler, i.e., BP.EXE or TPX.EXE. The real-mode version, TP.EXE, might run out of link memory. If you encounter that problem, set the linker option "link buffer" to "disk". If even that does not help, you can only use the command-line compiler.
       
   4. Borland Delphi:
      No choices are to be made at this level.
5. Declare the use of OptiVec functions in your program:
   • C/C++:
     Use #include directives to include the header files described in chapter 7.
     To get the whole OptiVec library at once, along with its new object-oriented interface, declare
     #include <OptiVec.h>
     To get only all vector functions (without the object-oriented interface),
     #include <VecAll.h>
     To add all data-fitting and matrix functions to that,
     #include <MatAll.h>.
     If you are writing MFC or Borland C++ ObjectWindows applications, any OptiVec header files should be included after the MFC or OWL header files.
   • Pascal/Delphi:
     Declare the use of OptiVec units as usual with the "uses" statement. The OptiVec units are grouped according to the data type. See chapter 7. In Delphi, OptiVec units should always be used together with the WinProcs unit, as some data types are borrowed from it.
6. Borland C/C++ 16-bit programs only:
   • If the linker option "process extended dictionaries" is available in your version of Borland C++, you must switch it on. Otherwise, you might get a "Table limit exceeded" linker error.
   • OptiVec works with Borland (Turbo) C++, version 3.0 or higher. Since, from version 4.0 on, Borland changed the name of the error handling routine matherr (without underbar) into _matherr (with a leading underbar), any 16-bit program using OptiVec has to call a macro, NEWMATHERR, which takes care of redirecting calls to _matherr, if necessary. You should place the call to NEWMATHERR into the module containing main() or OwlMain():
     #include .....
     #include <VecAll.h>
     NEWMATHERR
     int main( void )
     { .......... }
     If you forget to call NEWMATHERR, you will get a linker error "Unresolved external _matherr" in the Borland C versions from 4.0 on. Inclusion of the macro NEWMATHERR is not needed for 32-bit programs.
7. Have a look into the sample programs:
   • VDEMOW.CPP and FITDEMOW.CPP (C/C++, all Windows models)
   • VDEMOB.BPR and FITDEMOB.BPR (project files for Borland C++ Builder 4 or higher)
     
   • VDEMO.CPP and FITDEMO.CPP (Borland C++, DOS)
   • VDEMOW1.CPP and VDEMOW2.CPP (use only with Borland's OWL)
   • CDEMO.CPP shows a very simple example for the use of CMATH functions.
      
   • VDEMO.DPR and FITDEMO.DPR (Delphi projects)
   • VDEMO.PAS and FITDEMO.PAS (Borland Pascal, DOS)
   • CDEMO.PAS (Borland Pascal and Delphi console application)

Back to Table of Contents

---

2. Elements of OptiVec Routines

2.1 Synonyms for Some Data Types

a) C/C++ only:

The 64-bit integer data type (__int64 in BC++ Builder and MS Visual C++, Int64 in Delphi, Comp in Turbo Pascal) is called quad (for "quadword integer") in OptiVec.
The type quad is always signed. At present, OptiVec does not offer functions for unsigned 64-bit integers.

• Borland C++ only: In order to maintain compatibility with older BC versions (which did not directly support 64-bit integers), the data type quad is implemented as a struct of two 32-bit values. Floating-point numbers (preferably long doubles with their 64-bit mantissa) have to be used as intermediates. The necessary interface functions are setquad, quadtod and _quadtold. Alternatively, the two 32-bit halves may explicitly be set, as in:
  xq.Hi = 0x00000001UL;
  xq.Lo = 0x2468ABCDUL;

The data type extended, which is familiar to Pascal/Delphi programmers, is defined as a synonym for "long double" in OptiVec for C/C++. As Visual C++ does not support 80-bit reals, we define "extended" as "double" in the OptiVec versions for that compiler.
The reason for the choice of the name "extended" is that all OptiVec routines shall have identical names in C/C++ and Pascal/Delphi languages. Since the function prefixes are derived from the data types of the processed vectors (see below), this necessitates the definition of alias names for some data types denoted differently in the various languages. While the letter "L" (which could possibly stand for "long double") is already overcrowded by the data types long int and unsigned long, the letter "E" is unique to the data type extended and therefore used in the prefixes for vectors and functions of long double precision. This way, the letters defining the real- number data types are in alphabetical proximity: "D" for double, "E" for extended, and "F" for float. Maybe the future will bring high-precision 128-bit and 256-bit real numbers which could find their place in this series as "G" for "great" and "H" for "hyper".

b) Pascal/Delphi only:

For historical reasons, the various integer data types have a somewhat confusing nomenclature in Turbo Pascal. The WinProcs unit of Delphi offers already a more systematic nomenclature. In order to make the derived function prefixes compatible with the C/C++ versions of OptiVec, we define those synonyms present in Delphi (and a few more) also for 16-bit Pascal, as described in the following table:  

type	Pascal name	synonym	derived prefix
8 bit signed	ShortInt	ByteInt	VBI_
8 bit unsigned	Byte	UByte	VUB_
16 bit signed	SmallInt		VSI_
16 bit unsigned	Word	USmall	VUS_
32 bit signed	LongInt		VLI_
32 bit unsigned		ULong	VUL_
64 bit signed	Comp	QuadInt	VQI_
16/32 bit signed	Integer		VI_
16/32 bit unsigned	Cardinal	UInt	VU_

Turbo Pascal only:
The unsigned 32-bit integer type ULong is treated as such only inside OptiVec routines. Otherwise, all ULong variables will be treated as LongInt. This means that the most significant bit will then be interpreted as the sign bit, which may lead to errors, unless proper care is taken to avoid mistakes. Delphi 4+ always treats ULong as such.
QuadInts are always signed. As yet, there is nothing like a "UQuad".

Delphi:
As Delphi supports 64-bit integers, QuadInt is not defined as Comp, but is used as a synonym for the data type Int64.

To have a Boolean data type available which is of the same size as Integer, we define the type IntBool. It is equivalent to WordBool in Pascal, but LongBool in Delphi. You will see the IntBool type as the return value of many mathematical VectorLib functions.

Back to Table of Contents

2.2 Complex Numbers:
The Data Types fComplex, dComplex, eComplex, fPolar, dPolar, and ePolar

Most compilers and available libraries implement complex functions very inefficiently and inaccurately. (Just writing down the textbook formula for a complex function, like it is usually done, works fine only for a very limited range of arguments!)

Our aims are

• to make the use of complex numbers of all three data types possible in Pascal/Delphi and C as well as in C++,
• to support both cartesian and polar coordinates
• to allow for the most efficient implementation of all complex operations, using assembler code instead of C++ templates,
• and to introduce an easy, compact and consistent nomenclature.

VectorLib itself contains the necessary initialization functions of complex numbers and all vectorized forms of complex math functions. If you are using only these, you need not explicitly include CMATH. In this case, the following complex data types are defined in <VecLib.h> for C/C++:
typedef struct { float Re, Im; } fComplex;
typedef struct { double Re, Im; } dComplex;
typedef struct { extended Re, Im; } eComplex;
typedef struct { float Mag, Arg; } fPolar;
typedef struct { double Mag, Arg; } dPolar;
typedef struct { extended Mag, Arg; } ePolar;
(the data type extended is used as a synonym for long double, see above.)

The corresponding definitions for Pascal/Delphi are contained in the unit VecLib:
type fComplex = record Re, Im: Float; end;
type dComplex = record Re, Im: Double; end;
type eComplex = record Re, Im: Extended; end;
type fPolar = record Mag, Arg: Float; end;
type dPolar = record Mag, Arg: Double; end;
type ePolar = record Mag, Arg: Extended; end;

If, for example, a complex number z is declared as "fComplex z;", the real and imaginary parts of z are available as z.Re and z.Im, resp. Complex numbers are initialized either by setting the constituent parts separately to the desired value, e.g.,
z.Re = 3.0; z.Im = 5.7;
p.Mag = 4.0; p.Arg = 0.7;
(of course, the assignment operator is := in Pascal/Delphi).
Alternatively, the same initialization can be accomplished by the functions fcplx or fpolr:
C/C++:
z = fcplx( 3.0, 5.7 );
p = fpolr( 4.0, 0.7 );
Pascal/Delphi:
fcplx( z, 3.0, 5.7 );
fpolr( p, 3.0, 5.7 );

For double-precision complex numbers, use dcplx and dpolr, for extended-precision complex numbers, use ecplx and epolr.
Pointers to arrays or vectors of complex numbers are declared using the data types cfVector, cdVector, and ceVector (for cartesian complex) and pfVector, pdVector, and peVector (for polar complex) described below.

Back to Table of Contents

2.3 Vectors and Arrays:
The Data Types fVector, dVector, eVector,
cfVector, cdVector, ceVector, pfVector, pdVector, peVector,
iVector, biVector, siVector, liVector, qiVector,
uVector, ubVector, usVector, ulVector, and uiVector

The basis of all VectorLib routines is formed by the various vector data types given below and declared in <VecLib.h> or the unit VecLib. In contrast to the fixed-size static arrays, the VectorLib types use dynamic memory allocation and allow for varying sizes. Because of this increased flexibility, we recommend that you predominantly use the latter. Here they are:
 

C/C++ typedef float * fVector typedef double * dVector typedef extended * eVector typedef fComplex * cfVector typedef dComplex * cdVector typedef eComplex * ceVector typedef fPolar * pfVector typedef dPolar * pdVector typedef ePolar * peVector typedef int * iVector typedef byte * biVector typedef short * siVector typedef long * liVector typedef quad * qiVector typedef unsigned * uVector typedef unsigned byte * ubVector typedef unsigned short * usVector typedef unsigned long * ulVector typedef ui * uiVector

Pascal/Delphi type fVector = ^Float; type dVector = ^Double; type eVector = ^Extended; type cfVector = ^fComplex; type cdVector = ^dComplex; type ceVector = ^eComplex; type pfVector = ^fPolar; type pdVector = ^dPolar; type peVector = ^ePolar type iVector = ^Integer; type biVector = ^ByteInt; type siVector = ^SmallInt; type liVector = ^LongInt; type qiVector = ^QuadInt; type uVector = ^UInt; type ubVector = ^UByte; type usVector = ^USmall; type ulVector = ^ULong;

Internally, a data type like fVector means "pointer to float", but you may think of a variable declared as fVector rather in terms of a "vector of floats".
 

Note: in connection with Windows programs, often the letter "l" or "L" is used to denote "long int" variables. In order to prevent confusion, however, the data type "long int" is signalled by "li" or "LI", and the data type "unsigned long" is signalled by "ul" or "UL". Conflicts with prefixes for "long double" vectors are avoided by deriving these from the alias name "extended" and using "e", "ce", "E", and "CE", as described above and in the following.

 
C/C++ specific:
Vector elements can be accessed either with the [] operator, like VA[375] = 1.234;
or by the type-specific functions VF_element (returns the value of the desired vector element, but cannot be used to overwrite the element) and VF_Pelement (returns the pointer to a vector element). The latter function may be used to set vector values, e.g.
*VF_Pelement( X, 3 ) = 5.7;
Especially for some older Borland C versions (which have a bug in the pointer-arithmetics), VF_Pelement has to be used instead of the syntax X+n.
In your programs, you may mix these vector types with the static arrays of classic C style.
For example:
float a[100]; /* classic static array */
fVector b=VF_vector(100); /* VectorLib vector */
VF_equ1( a, 100 ); /* set the first 100 elements of a equal to 1.0 */
VF_equC( b, 100, 3.7 ); /* set the first 100 elements of b equal to 3.7 */

Pascal/Delphi specific:
The elements of OptiVec vectors cannot be accessed with the [] operator here. Instead, the the type-specific functions VF_element (returns the value of the desired vector element, but cannot be used to overwrite the element) and VF_Pelement (returns the pointer to a vector element) have to be used. The latter function allows to set vector values, e.g.
VF_Pelement( X, 3 )^ := 5.7;
As in C/C++, you may mix the OptiVec vector types with the static arrays of classic Pascal style. Static arrays have to be passed to OptiVec functions with the "address of" operator. Here, the above example reads:
a: array[0..99] of Single; (* classic static array *)
b: fVector;(* VectorLib vector *)
b := VF_vector(100);
VF_equ1( @a, 100 ); (* set first 100 elements of a = 1.0 *)
VF_equC( b, 100, 3.7 ); (* set first 100 elements of b = 3.7 *)
Since Version 4, Delphi has also offered dynamically-allocated arrays, which may also be used as arguments for OptiVec functions. The following table compares the pointer-based vectors of VectorLib with the array types of Pascal/Delphi:
 

	OptiVec vectors	Pascal/Delphi static/dynamic arrays
alignment of first element	on 32-byte boundary for optimum cache-line matching	2 or 4-byte boundary (may cause line-break penalty for double, QuadInt)
alignment of following elements	packed (i.e., no dummy bytes between elements, even for 10- and 20-bit types	arrays must be declared as "packed" for Delphi to be compatible with OptiVec
index range checking	none	automatic with built-in size information
dynamic allocation	function VF_vector,  VF_vector0	procedure SetLength (Delphi only)
initialization with 0	optional by calling VF_vector0	always (Delphi only)
de-allocation	function V_free,  V_freeAll	procedure Finalize (Delphi only)
reading single elements	function VF_element: a := VF_element(X,5); Delphi only: typecast into array also possible: a := fArray(X)[5];	index in brackets: a := X[5];
setting single elements	function VF_Pelement: VF_Pelement(X,5)^ := a; Delphi only: typecast into array also possible: fArray(X)[5] := a;	index in brackets: X[5] := a;
passing to OptiVec function	directly: VF_equ1( X, sz );	address-of operator: VF_equ1( @X, sz );
passing sub-vector to OptiVec function	function VF_Pelement: VF_equC( VF_Pelement(X,10), sz-10, 3.7);	address-of operator: VF_equC( @X[10], sz-10, 3.7 );

 
Summarizing the properties of OptiVec vectors and of Pascal/Delphi arrays, the latter are somewhat more convenient and, due to the index range checking, safer, whereas the pointer-based OptiVec vectors are processed faster (due to the better alignment and to the absence of checking routines).

Back to Table of Contents

2.4 Real-number Functions:
The Prefixes VF_,  VD_, and VE_

Any of the algebraic and mathematical functions included in this library exists in one variant for each floating-point format. The data type of all floating-point vector elements, parameters, and of the return value is always the same within one function. The data type is signalled by the second letter of the prefix: VF_ denotes the variant of a function that uses exclusively the data type float (Pascal: Single), VD_ stands for the data type double, and VE_ for the data type extended, i.e., long double. (The first letter, "V", stands for "Vector function", of course.) VF_ functions thus work on arrays declared as fVector, use parameters of the type float, and, if there is any floating-point return value, this will also be of the type float. Except for a very few cases, there are no mixed-type functions (that would, e.g., work on vectors of type fVector, use parameters of type double and return a value of type long double).

One partial exception from this rule comes from the fact that floating-point return values of OptiVec functions are returned in extended precision on the number stack. Therefore, you may assign the return value of a function to a variable of another data type. For example, the product of all elements of a vector may easily overflow, and it is a good idea to define eProd as an extended (i.e., as a long double), before writing the line
eProd = VF_prod( X, size );

Borland C++ only:
To use this possibility, you must switch the option "Fast floating point" on (in the IDE in the menu "Options/Compiler/Advanced Code Generation", or the command-line compiler option "-ff"),

For the description of the functions in the Alphabetical Reference, generally only the VF_ version is described and its syntax explicitly given. The versions for the data types double and long double are exactly analogous to the VF_ variant. You have only to replace the prefix VF_ by VD_ (or VE_) and to use "dVector" and "double" (or "eVector" and "extended", resp.) wherever you find "fVector" and "float" in the VF_ version.

Back to Table of Contents

2.5 Complex-number Functions:
The Prefixes VCF_,  VCD_,  VCE_,  VPF_,  VPD_, and VPE_

Return values of the complex data types are not possible in Pascal/Delphi. Therefore, the syntax of those functions returning a complex number is different in C/C++ and Pascal/Delphi.

In contrast to the carelessness with which complex mathematical functions are often treated (see above), the complex functions of OptiVec are designed in such a way as to achieve full accuracy over the complete range of input/output values possible with the respective data type.

In order to perform non-vectorized complex operations with the same level of speed and reliability as the vectorized ones, use CMATH. See CMATH.HTM for details.

Back to Table of Contents

2.6 Functions of the Integer Data Types:
The Prefixes VI_,  VBI_,  VSI_,  VLI_,  VQI_,
VU_,  VUB_,  VUS_,  VUL_, and VUI_

Don't be afraid of so many data types. It is one of the advantages of modern computer languages to have them, and it is one of the disadvantages, at the same time, that a programming style is supported which mixes all the data types until it is no longer clear "who is who". In all normal cases, the VI_,  VLI_, and VU_ functions should be sufficient; but keep in mind that there are more available in case you need them.

If present, the vectorized integer functions are always described together with their floating-point analogues. To obtain, for example, the VI_ version, vectors of type iVector have to be substituted for those of type fVector which are demanded by the VF_ version. In the same way, the other versions are obtained by changing "float" and "fVector" into the desired data type.

Back to Table of Contents

2.7 Common Functions of Several Data Types: The Prefix V_

Back to Table of Contents

---

3. VecObj, theObject-Oriented Interface for VectorLib

• automatic allocation and deallocation of memory
• simplified vector handling
• greatly reduced risk of memory leaks
• increased memory access safety
• intuitive overloaded operators
• simpler function calls

• increased compiler load
• larger overhead (as for any encapsulated C++ code!), leading to
• increased code size
• decreased computational efficiency
• vectors can be processed only as a whole, not in parts

MS Visual C++ and Borland C++ Builder (but not previous Borland C++ versions): Programmers should put the directive
"using namespace OptiVec;"
either in the body of any function that usestVecObj, or in the global declaration part of the program. Placing the directive in the function body is safer, avoiding potential namespace conflicts in other functions.
The vector objects are defined as classes vector<T>, encapsulating the vector address (pointer) and size.
For easier use, these classes got alias names fVecObj, dVecObj, and so on, with the data-type signalled by the first one or two letters of the class name, in the same way as the vector types described above.

All functions defined in VectorLib for a specific vector data-type are contained as member functions in the respective tVecObj class.
The constructors are available in four forms:
vector(); // no memory allocated, size set to 0
vector( ui size ); // vector of size elements allocated
vector( ui size, T fill ); // as before, but initialized with value "fill"
vector( vector<T> init ); // creates a copy of the vector "init"

For all vector classes, the arithmetic operators
+    -    *    /    +=    -=    *=    /=
are defined, with the exception of the polar-complex vector classes, where only multiplications and divisions, but no additions or subtractions are supported. These operators are the only cases in which you can directly assign the result of a calculation to a vector object, like
fVecObj Z = X + Y; or
fVecObj Z = X * 3.5;
Note, however, that the C++ class syntax rules do not allow a very efficient implementation of these operators. The arithmetic member functions are much faster. If speed is an issue, use
fVecObj Z.addV( X, Y ); or
fVecObj Z.mulC( X, 3.5 );
instead of the operator syntax.
The operator * refers to element-wise multiplication, not to the scalar product of two vectors.

All other arithmetic and math functions can only be called as member functions of the respective output vector as, for example, Y.exp(X). Although it would certainly be more logical to have these functions defined in such a way that you could write "Y = exp(X)" instead, the member-function syntax was chosen for efficiency considerations: The only way to implement the second variant is to store the result of the exponential function of X first in a temporary vector, which is then copied into Y, thus considerably increasing the work-load and memory demands.

While most VecObj functions are member functions of the output vector, there is a number of functions which do not have an output vector. In these cases, the functions are member functions of an input vector.
Example: s = X.mean();.

If you ever need to process a VecObj vector in a "classic" plain-C VectorLib function (for example, to process only some part of it), you may use the member functions
getSize() to retrieve its size,
getVector() for the pointer (of data type tVector, where "t" stands for the usual type prefix), and
Pelement( n ) for a pointer to the to the n'th element.

The syntax of all VecObj functions is described in FUNCREF.HTM together with the basic VectorLib functions for which tVecObj serves as a wrapper.

Back to Table of Contents

---

4. VectorLib Functions and Routines: A Short Overview

4.1 Generation, Initialization and De-Allocation of Vectors

The following functions manage dynamically allocated vectors: 

VF_vector	memory allocation for one vector
VF_vector0	memory allocation and initialization of all elements with 0
V_free	free one vector
V_nfree	free n vectors (only for C, not for Pascal)
V_freeAll	free all existing vectors

 
You should always take proper care to de-allocate 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.
You might wonder why we add still more memory allocation functions to the already rich omnium gatherum of C/C++ and Pascal/Delphi. The reason is that, for every environment and every memory model, the most appropriate memory management functions shall be selected automatically. This means that you, the user, need not deal yourself with the various methods, but can leave this task to OptiVec. Moreover, this makes your programs more easily portable.

Performance tips:

• In the 32 bit versions, the vectors allocated by VF_vector etc. are aligned on 64 byte boundaries for optimum cache-line matching (Intel Pentium XX: 32 byte, AMD Athlon: 64 byte). On the other hand, static arrays as well as vectors created by the operator new or by the standard functions, malloc, calloc, GetMem, LocalAlloc, GlobalAlloc etc. are aligned on 4 byte boundaries only. Consequently, for optimum performance, you should use only vectors allocated by VF_vector etc.
• The SIMD commands employed in the P6 version require data to be aligned on 16 byte boundaries. Once more: Use the dynamic vectors of OptiVec to guarantee the necessary alignment. The penalty for not properly aligned data may amount to 25%.
• Instead of many small vectors, consider allocating one large vector. Define the small vectors as parts of the larger one:
  

  C/C++: X = VF_vector( 3*size); Z = (Y = X+size) + size;

  Pascal/Delphi: X := VF_vector( 3*size ); Y := VF_Pelement( X, size ); Z := VF_Pelement( Y, size );

  Be sure size is rounded up so as to make size*sizeof( data type ) a multiple of 32 or 64.
• Avoid too frequent allocation and deallocation. Try to re-use vectors instead.

The following functions are used to initialize or re-initialize vectors that have already been created: 

VF_equ0	set all elements of a vector equal to 0
VF_equ1	set all elements equal to 1
VF_equm1	set all elements equal to -1
VF_equC	set all elements equal to a constant C
VF_equV	make one vector a copy of another
VFx_equV	"expanded" version of the equality operation: Yi = a * Xi + b
VF_ramp	"ramp": Xi = a * i + b.
VF_random	high-quality random numbers
VF_noise	white noise
VF_comb	"comb": equals a constant C at equidistant points, elsewhere 0

 
The following functions generate windows for use in spectral analysis: 

VF_Hanning	Hanning window
VF_Parzen	Parzen window
VF_Welch	Welch window

 
Complex vectors may be initialized by these functions: 

VF_ReImtoC	merge two vectors, Re and Im, into one cartesian complex vector
VF_RetoC	overwrite the real part of a cartesian complex vector
VF_ImtoC	overwrite the imaginary part of a cartesian complex vector
VF_PolartoC	construct a cartesian complex vector from polar coordinates, entered as separate vectors Mag and Arg
VF_MagArgtoP	merge two vectors, Mag and Arg into one polar complex vector
VF_MagArgtoPrincipal	merge two vectors, Mag and Arg into one polar complex vector, reducing the Arg range to the principal value, -p < Arg <= +p
VF_MagtoP	overwrite the Mag part of a polar complex vector
VF_ArgtoP	overwrite the Arg part of a polar complex vector
VF_ReImtoP	construct a polar complex vector from cartesian coordinates, entered as separate vectors Re and Im

Back to Table of Contents

4.2 Index-oriented Manipulations

Back to Table of Contents

4.3 Data-Type Interconversions

Back to Table of Contents

4.4 More about Integer Arithmetics

Back to Table of Contents

4.5 Basic Functions of Complex Vectors

Back to Table of Contents

4.6 Mathematical Functions

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 data-type 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 error-free, the return value is FALSE (0), otherwise it is TRUE (any non-zero number).

Back to Table of Contents

4.6.1 Rounding

Back to Table of Contents

4.6.2 Comparisons

Back to Table of Contents 

4.6.3 Direct Bit-Manipulation

Back to Table of Contents

4.6.4 Basic Arithmetics, Accumulations

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. 

VFx_addV	Zi = (a * Xi + b) + Yi
VFx_divrV	Zi = Yi / (a * Xi + b)

 
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_: 

VFs_addV	Zi = C * (Xi + Yi)
VFs_subV	Zi = C * (Xi - Yi)
VFs_mulV	Zi = C * (Xi * Yi)
VFs_divV	Zi = C * (Xi / Yi)

 
Other simple operations include: 

VF_maxC	set Yi equal to Xi or C, whichever is greater
VF_minC	choose the smaller of Xi and C
VF_maxV	set Zi equal to Xi or Yi, whichever is greater
VF_minV	set Zi equal to Xi or Yi, whichever is smaller
VF_limit	limit the range of values
VF_flush0	set all values to zero which are below a preset threshold
VF_intfrac	split into integer and fractional parts
VF_mantexp	split into mantissa and exponent

 
While, in general, all OptiVec functions are for input and output vectors of the same type, the arithmetic functions exist also for mixed-type operations between the floating-point and the integer types. The result is always stored in the floating-point type. Examples are:
 

VF_addVI	fVector Z = fVector X + iVector Y
VD_mulVUL	dVector Z = dVector X * ulVector Y
VE_divrVBI	eVector Z = biVector Y / eVector X

Similarly, there exists a family of functions for the accumulation of data in either the same type or in higher-precision data types. Some examples are: 

VF_accV	fVector Y += fVector X
VD_accVF	dVector Y += fVector X
VF_accVI	fVector Y += iVector X
VQI_accVLI	qiVector Y += liVector X

 
Additionally, within the floating-point data-types, you can accumulate two vectors at once:  

VF_acc2V	fVector Y += fVector X1 + fVector X2
VD_acc2VF	dVector Y += fVector X1 + fVector X2

Back to Table of Contents 

4.6.5 Geometrical Vector Arithmetics

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:

VF_rotateCoordinates	counter-clockwise rotation of the input coordinates specified by the vectors X and Y; the result is returned in the vectors Xrot and Yrot.
VCF_rotateCoordinates	counter-clockwise rotation of the input coordinates specified by the cartesian complex vector XY; the result is returned in the vector XYrot.

Back to Table of Contents 

4.6.6 Powers

The complex-number equivalents are available as well, both for cartesian and polar coordinates. Additionally, two special cases are covered:
 

VCF_powReExpo	real, fractional powers of complex numbers
VCF_exptoP	takes a cartesian input vector, returning its exponential function in polar coordinates.

Back to Table of Contents 

4.6.7 Exponentials and Hyperbolic Functions

Back to Table of Contents 

4.6.8 Logarithms

Back to Table of Contents 

4.6.9 Trigonometric Functions

Back to Table of Contents 

4.7 Analysis

The complex equivalents of the last group of functions are:
 

VCF_maxReIm	maximum real and imaginary parts separately
VCF_minReIm	minimum real and imaginary parts separately
VCF_absmaxReIm	maximum absolute real and imaginary values separately
VCF_absminReIm	minimum absolute real and imaginary values separately
VCF_absmax	largest magnitude (absolute value; this is a real number)
VCF_absmin	smallest magnitude
VCF_cabsmax	complex number of largest magnitude
VCF_cabsmin	complex number of smallest magnitude
VCF_sabsmax	complex number for which the sum |Re| + |Im| is largest
VCF_sabsmin	smallest complex number in terms of the sum |Re| + |Im|
VCF_absmaxind	largest magnitude (absolute value) and its index
VCF_absminind	smallest magnitude and its index

 
Sums, products, etc. are available by functions grouped as statistical building blocks and summarized in chapter 4.9. 

Back to Table of Contents 

4.8 Signal Processing:
Fourier Transforms and Related Topics

The FFT algorithm chosen for this PC implementation is a radix-2 Cooley-Tukey routine. Only for this radix-2 algorithm, the restricted number of eight coprocessor registers still allows to hold all intermediate results of the inner transform loop in coprocessor registers. Although featuring savings in the number of multiplications, radix-4 and radix-8 routines are rendered less efficient than the routine chosen by the need of storing intermediate results in memory.
There are three different versions of all FFT-based functions. Depending on the memory model, either of them is automatically chosen. You may, however, explicitly specify the one you wish to employ.

• The first version uses the already-mentioned table of sine values (see chapter 4.6.9. and the function VF_sinrpi2) as a look-up table for the Fourier coefficients needed. This table needs up to 10 kBytes in the 16-bit models and 40 kBytes in the 32-bit models. By default, this variant is used in the memory models COMPACT and LARGE. To explicitly specify it in the other memory models, please use the prefixes VFl_,  VDl_,  VEl_ (with the letter "l" for the "larger" amount of memory needed).
• The second variant, which is automatically chosen in the memory models SMALL, MEDIUM, and HUGE, employs trigonometric recursions to obtain the sine and cosine values with still satisfactory speed, though this procedure is not as fast as simply reading them from a table. You may explicitly specifiy this variant by adding the letter "s" (for the "smaller" amount of memory needed) in the function prefix. Examples are VFs_FFT,   VDs_convolve,   VEs_spectrum.
  If you decide to use this variant in order to economize memory in the models COMPACT and LARGE, use the prefix VFs_ for all(!) routines employing FFT. Otherwise, you might happen to load not only a second FFT routine, but also its whole look-up table into your already overcrowded memory.
• The new "parallel-enhanced" variant with the prefix VFp_, finally, uses additional buffer memory to temporarily re-order the input vector in such a way as to optimize both cache utilization and (in the Pentium III libraries) the use of SIMD commands. The minimum input vector size is 16. Below that, the VFp_ functions automatically pass the task on to the respective VFs_ function. For medium-size vectors, the VFp_ version is about 20 percent faster than the other two variants. For large vectors (above the L2 cache size), the speed gain increases to a factor of about 1.8. The analogous 2D-FFT for matrices – where the amount of attainable parallelism is obviously even larger – a speed increase by about a factor of 2.5 is obtained (measured for the Pentium III libraries; with the 486 libraries, the gain is 10% for medium-size vectors, up to a factor of 1.6 for large vectors, and about 30% for matrices). For extremely large vector sizes near or above the size of available RAM, however, the need of additional (virtual) memory slows execution down to a speed again comparable to the VFs_ version. The VFp_ version is automatically chosen for 32-bit programs (i.e., in the memory model FLAT).

As all FFT-based matrix functions internally rely on VF_FFT, all of them exist in three versions as well. Here, the prefixes are MFp_,  MFl_ and MFs_ in the real-number case, or MCFp_,  MCFl_ and MCFs_ in the complex case. Similarly to the one-dimensional case, the functions with the "normal" prefix (MF_,  MCF_) will automatically be redirected to the MFP_,  MFl_ or MFs_ variant, as determined by the memory model.

Although it does not use Fourier transform methods, VF_smooth should be remembered here as a crude form of frequency filtering which removes high-frequency noise.

Back to Table of Contents 

4.9 Statistical Functions and Building Blocks

Back to Table of Contents 

4.10 Data Fitting

A detailed description of the various data-fitting concepts is given in chapter 13 of MATRIX.HTM. Therefore, at this place, the available X-Y fitting functions are only summarized in the following table:
 

VF_linregress	equally-weighted linear regression on X-Y data
VF_linregresswW	the same with non-equal weighting
VF_polyfit	fitting of one X-Y data set to a polynomial
VF_polyfitwW	the same for non-equal data-point weighting
VF_linfit	fitting of one X-Y data set to an arbitrary function linear in its parameters
VF_linfitwW	the same for non-equal data-point 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 X-Y data set to an arbitrary, possibly non-linear function
VF_nonlinfitwW	the same for non-equal data-point weighting
VF_multiLinfit	fitting of multiple X-Y data sets to one common linear function
VF_multiLinfitwW	the same for non-equal data-point weighting
VF_multiNonlinfit	fitting of multiple X-Y data sets to one common nonlinear function
VF_multiNonlinfitwW	the same for non-equal data-point weighting

 

Back to Table of Contents 

4.11 Input and Output

The following functions allow to modify the standard settings of VF_write,   VF_nwrite and VI_read: 

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 whole-number variants of the V.._read functions

Back to Table of Contents 

4.12 Graphics

VectorLib distinguishes between two sorts of plotting functions, AutoPlot and DataPlot. All AutoPlot functions (e.g., VF_xyAutoPlot) execute the following steps:

1. define a viewport within the plotting region (which is either the default region or the one defined by calling V_setPlotRegion)
2. clear the viewport
3. generate a Cartesian coordinate system with suitably scaled and labeled axes
4. plot the data according to the parameters passed to the function

Cartesian complex arrays are printed into the complex plane (the imaginary parts versus the real parts), using
 

VCF_autoPlot	plot one cartesian complex vector
VCF_2AutoPlot	plot two cartesian complex vectors simultaneously
VCF_dataPlot	plot one additional cartesian complex vector

At present, there are no plotting functions for polar complex vectors included.
It is possible to draw more than one coordinate systems into a given window on the screen. The position of each coordinate system must be specified by the above-mentioned function V_setPlotRegion. "Hopping" between the different coordinate systems and adding new DataPlots after defining new viewports (e.g., for text output) is made possible by the following functions:
 

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

DOS only:
When using multiple coordinate systems on the same screen, the default font used for axis labeling might be too large, so that neighbouring labels overlap each other. In these cases, use the BGI function settextstyle to switch to another font before calling an AutoPlot function.

Back to Table of Contents 

---

5. Error Handling

5.1 General Remarks

In the "expanded" versions of all functions with extended accuracy (those with the prefixes VEx_ and VCEx_; for example VEx_exp), there is generally no overflow protection for the calculation of A*X_i+B, but only for the core of the function itself and for the final multiplication by C.

A series of identical errors occurring within one and the same OptiVec function leads to one error message only. Subsequent identical messages are suppressed.

There is a fundamental difference between floating-point and integer numbers with respect to OVERFLOW and DOMAIN errors: for floating-point numbers, these are always serious errors, whereas for integer numbers, by virtue of the implicit modulo-2ⁿ arithmetics, this is not necessarily the case. In the following two paragraphs, details are given on the error handling of integer and floating-point numbers, respectively.

Back to Table of Contents

5.2 Integer Errors

Although you may use a call to
V_setIntErrorHandling( ierrIgnore );
to switch the error handling off, it is always better simply to use the "normal" VI_ version rather than the VIo_ version with the error-handling short-cut, as the normal version is always much faster.

C/C++ only:
To choose the overflow-detecting version not only for single function calls, but everywhere, the easiest way is to define symbolic constant V_trapIntError in the program header before(!) <VecLib.h> is included:
Example:
#define V_trapIntError 1
#include <VIstd.h>
#include <VImath.h>
.....
main() /* or WinMain(), or OwlMain() */
{
  iVector I1, I2;
  I1 = VI_vector( 1000 ); I2 = VI_vector( 1000 );
  V_setIntErrorHandling( ierrNote );
  VI_ramp( I1, 1000, 0, 50 ); /* an overflow will occur here! */
  V_setIntErrorHandling( ierrIgnore );
  VI_mulC( I2, I1, 1000, 5 );
    /* here, even a whole series of overflows will occur; they are all ignored. */
  ....
}

Back to Table of Contents

5.3 Floating-Point Errors

5.3.1 C/C++ specific

If the function in which an error occurs has one real-valued argument, only the parameter e->x is defined in calling _matherr and e->y is left undefined. Only if there are two arguments (like in VF_atan2 or in VF_cotrpi), both e->x and e->y are needed to hold these arguments. For complex arguments, the real part (or the Mag part for polar coordinates) is stored in e->x and the imaginary part (or the Arg part) in e->y.

Back to Table of Contents

5.3.2 Pascal/Delphi specific

Back to Table of Contents

5.3.3 Error Types (Both C/C++ and Pascal/Delphi)

In the following description of all floating-point error types, we denote by "HUGE_VAL" the largest number possible in the respective data type. Similarly, "TINY_VAL" is the smallest denormal number representable in the respective data type; this is not the same as "MIN_VAL", which is the smallest full-accuracy number of the respective data type.

• DOMAIN errors most often lead to the result NAN ("not-a-number"). Even if nothing happens within the function itself that detects a DOMAIN error, an uncontrolled program crash may result if subsequent operations are performed on the vector element set to NAN.
  For C/C++, we therefore recommend to modify _matherr and _matherrl in such a way that the program is aborted if a DOMAIN error occurs (for an example, see below; alternatively, the UNIX style may be adopted; see the file MATHERR.C supplied with the your C/C++ compiler). Changing the return value of _matherr is another possiblity, but the better way very clearly is to avoid any DOMAIN errors by performing appropriate checks before calling functions like VF_sqrt,  VF_log,  VF_atan2 etc.
  For Pascal/Delphi, we recommend not to change the default setting of V_FPErrorHandlingMode or to include "fperrAbortDOMAIN" in any changes.
  Note: the pseudo-numbers INF and NAN are not allowed as input for any functions of OptiVec. They are not tested for; their presence will normally result in a hardware interrupt.
• SING errors are treated like an extreme case of OVERFLOW (see below). In most cases, they arise from an implicit division by zero or from taking the logarithm of zero. The proposed result is never NAN, but always a "number", in most cases ±HUGE_VAL. Although it is recommended also in the case of SING errors to abort the program and take the necessary measures to avoid them, you may choose to continue program execution.
• OVERFLOW errors are the most abundant form of floating-point errors. They are always handled by proposing +HUGE_VAL or -HUGE_VAL as the result. Within many user algorithms, OVERFLOW errors may occur for intermediate results; if subsequent steps perform operations like taking the inverse, the final result may be acceptable despite the error. Therefore, we recommend to accept the return-value proposal and not to abort the program.
  C/C++ only: In principle, you may decide not to accept the return-value proposal of _matherr, but to substitute another one. However, for several reasons you are discouraged from doing that: the correct sign of the result is set by the calling ("complaining") function in many cases only after returning from _matherr; the x-value passed to _matherr (which should be inspected before the return value is modified) may either be X_i or (as in some of the expanded complex math functions of the VCEx_... family) the intermediate result x' = Ax + B. Note, furthermore, that all x-values are passed to _matherr as double-precision floating-point numbers, also in the case of integer input numbers (like in VF_tanrpi, where P_i and q are passed as x and y to _matherr).
• TLOSS ("total loss of precision") errors are detected only if a more serious error might occur in the respective function. For example, the sine function takes on values between -1 and +1 for all arguments. So, in case of an argument too big for the sine function to be evaluated with any accuracy, the result may nevertheless be "tacitly" set to 0.0 and no call to the OptiVec error handler is generated (whereas Borland C++ chooses NAN, "not a number", as the result, which is certainly even less correct than arbitrarily choosing 0.0).
  On the other hand, the cosecant, i.e. the inverse of the sine, is not defined for arguments of integer multiples of p. Therefore, a more serious error (in this case a SING or an OVERFLOW error) might be hidden under the TLOSS for very big arguments. This possibility is taken into account by calling the error handler, although the proposed result is again set to 0.0 (which is the mean of the two extremes +HUGE_VAL and -HUGE_VAL). Generally, the default result in the case of a TLOSS error is the mean of the results for arguments of +0.0 and -0.0.
• UNDERFLOW errors are never detected; underflowing results are always "tacitly" set to denormal numbers or finally to 0.0 by the floating-point processor itself. Indeed, you may very rarely wish to do something else in this case.
• As in all non-vectorized math functions of the Borland compilers and Visual C++, PLOSS ("partial loss of precision") errors are never detected and precision problems simply ignored.

Back to Table of Contents

5.3.4 Borland C++ only:
Differences between Borland C++ 4.0 and earlier versions

Back to Table of Contents

5.4 The Treatment of Denormal Numbers

In general, they may be treated just as ordinary numbers. In some instances, however, like taking the inverse, overflow errors may occur. In these cases, the somewhat academic distinction between SING and OVERFLOW errors is dropped and a SING error signalled (as if it was a division by exactly 0).

On the other hand, for functions like the logarithms, very small input numbers may give perfectly reasonable results, although the exact number 0.0 is an illegal argument, leading to a SING error. Here, the possible loss of precision is neglected and denormals are considered valid arguments. (This treatment is quite different from that chosen for the math functions of most compilers, where denormal arguments lead to SING errors also in these cases, which seems less appropriate to us.)

Back to Table of Contents

5.5 Advanced Error Handling: Writing Messages into a File

You might wish to circumvent this. To this end, OptiVec provides the function V_setErrorEventFile. This function needs as arguments the desired name of your event file and a switch named ScreenAndFile which decides if the error message is printed only into the file, or additionally to the screen as well.
Note that this redirection of error messages is valid only for errors occurring in OptiVec routines. If you wish to do so, however, there is a way in C/C++ to extend the redirection also to the "non-OptiVec" functions: you may modify _matherr and _matherrl such that the statement
return 0;
(which signals an unresolved error) is replaced by the sequence
V_noteError( e->name, e->type ); return 1;
Thereby the task of printing the error message for unresolved errors is passed to the OptiVec function V_noteError. Keep in mind that it is the return value of _matherr which decides if an error message is printed by the default error handler of your compiler. Thus, after the call to V_noteError, the printing of the default error messages is by-passed by returning "1". (Also, do not forget that OptiVec uses your _matherr routine to determine which errors you accept and which not!)

For example, your _matherr function (matherr – without the leading underbar – for Borland C++ 3.0 and 3.1) might look like the following one:
#include <math.h>
int _matherr( struct exception *e) /* "_exception" for MSVC */
{
  if( (e->type == UNDERFLOW) || (e->type == TLOSS) ) ; /* ignore */
  else /* all other errors deserve at least notice */
  {
    V_noteError( e->name, e->type );
    if (e->type == DOMAIN) exit(1); /* really fatal */
  }
  return 1;
}
(Of course, if you decide to change _matherr, do not forget to change _matherrl in the same way, if you are using Borland C++!).

Both C/C++ and Pascal/Delphi: The default printing of error messages on the screen alone is restored by V_closeErrorEventFile.

A way to keep track also of those errors which do not lead to messages is opened by the return values of mathematical VectorLib functions. Any of the "silent" TLOSS along with the more serious DOMAIN, SING and OVERFLOW errors will lead to a TRUE (non-zero) return value. You may wish to check for a clean result after a group of functions, like in the following example:
unsigned ErrFlag;
...
/* part Trig1 */
ErrFlag=0; /* reset the flag */
ErrFlag |= VF_sin( Y1, X1, sz );
ErrFlag |= VF_cos( Y2, X1, sz );
ErrFlag |= VF_atan2( Z1, Y1, Y2, sz );
if( ErrFlag ) V_printErrorMsg( "Errors occurred in part Trig1 ! ");
...
As indicated in the example, it is better to use the |= operator (Pascal/Delphi: "ErrFlag := ErrFlag or") instead of += (since, in rare cases, all return values might add up to 65536, which is stored as 0 due to an overflow of the integer variable). Even if you chose addition of the individual return values, the number of occurred errors would not be obtainable from the result; in case of an error, any non-specified non-zero number is returned.

Back to Table of Contents

5.6 OptiVec Error Messages

(00) OptiVec/CMATH not installed correctly (must use INSTALL.EXE !)

Shareware version only: Either you are running a program containing OptiVec functions on a different computer than the one on which you installed OptiVec. The distribution of applications containing OptiVec functions is possible only with the Registered version.
Or you attempted to install OptiVec by unzipping the package by hand, without using INSTALL.EXE. This is not possible, as INSTALL.EXE also starts the clock for the trial period. With Windows 2000 / XP, you have to run InitOVBC.EXE (Borland C++ version) or InitOVVC.EXE (MSVC version) instead of INSTALL.EXE.

(0) Trial period for OptiVec/CMATH has expired!

Shareware version only: Consider ordering the registered version!

(1) Not enough memory.

You are trying to allocate memory, but there is not enough left. This error occurs mostly in connection with "forgotten" vectors that are allocated but never freed. Try these solutions:
* Look out for vectors that might be no longer needed and free them as soon as possible. Be sure that any vectors allocated in subroutines are freed before leaving the subroutine.
* Are you still working with 16-bit models? If you need to work with large amounts of data, the memory model FLAT should be used, working with Win32, WindowsNT, or Windows95/98.
* Store data intermediately on disk, using VF_store, and retrieve them using VF_recall, when needed. This method is slow and should be used only if really unavoidable.

(2) Vector > 64 kB not possible (16-bit). (2) Vector > 4 GB not possible (32-bit).

* Either you are trying to allocate a vector whose size exceeds the maximum of 4 GB (32-bit) or 64 kB (16-bit except HUGE).
* Or you are in the HUGE model and attempt to process a huge vector in a function where the size is limited to 64 kB even in this model. This might happen, e.g., if the table is too large in one of the interpolation routines. In this case, you must either use the model FLAT or split up your problem into smaller vectors.

(3) Vectors/matrices must not be identical.

In some functions where more than one input vector (or matrix) is used to calculate more than one output vector (or matrix), attention has to be paid, which output data may or may not overwrite which input data. See the specification of the function where the error occurred.

(4) Cannot use requested format (too many entries per line).

This error occurs with the printing functions. The parameter nperline was chosen too large. The function automatically selects the maximum nperline possible and continues execution, but you should nevertheless consider adapting your program.

(5) X-values of table must be distinct.

The routines performing interpolations need the tables to be ordered according to their x-values. Each x-value may occur only once, as it is impossible for one and the same x-value to belong to different y-values.

(6) Not possible with fewer than n elements.

Some functions require a minimum size of n elements of the vector processed.

(7) Not possible with more than n elements.

Some functions are limited to a maximum size of n elements. This is true, for example, for VF_polyinterpol, where only up to 10 table elements may be used for the each interpolation.

(8) Size must be an integer power of 2.

For all functions using – explicitly or implicitly – Fast Fourier Transform methods, the vector size has to be an integer power of 2. Enlarge or truncate your vector(s) to meet that condition.

(9) Invalid parameter(s).

In some functions, certain combinations of input parameters are illegal. For example, it is not possible to perform a 9-point interpolation on only 5 data points.

(10) Cannot scale symbols by more than a factor of 50.

(Windows only.) The symbols used in VectorLib plotting functions cannot be magnified by more than a factor of 50 (which means already filling the screen with a single symbol). Program execution is continued with a value of 50.0.

(11) Cannot use line thicker than 500 pixels.

(Windows only.) The lines used in VectorLib plotting functions cannot be thicker than 500 pixels (which is already nonsense). Program execution is continued with a value of 500.

(12) Cannot free non-existent vector.

You called V_free or V_nfree for a vector that has no memory allocated. Program execution is continued without freeing anything.

Back to Table of Contents

(21) Invalid dimension(s).

In one way or the other, the dimensions of input or output matrices do not meet the requirements.

(22) Matrix is singular.

In a function requiring regular input matrices, a singular matrix was encountered. Consider alternative functions, designed to handle (nearly) singular matrices.

(23) No convergence achieved.

Some iterative matrix methods may, in very rare cases, fail to achieve convergence.

(24) Only the first n elements of each row can be printed.

This error occurs with the matrix printing functions. The number of columns is too large for the available linewidth. The function automatically selects the maximum number of columns to be displayed and truncates the rows as needed.

---

6. Trouble-Shooting

6.1 General Problems

• The choice of the OptiVec library must match your selection of memory model, processor, and environment. With Borland C++, you are not going to have much fun with the library VCL3.LIB under Windows3.x (where you need VCL3W.LIB), and the libraries designed for Borland C++ will not work with Visual C++ or any other compiler. Similarly, OVVCSD.LIB, designed for single-thread debug in Visual C++, will not work in any multi-thread or any "release" link.
• You must not use vectors with a size of 0. All functions tacitly assume that the vectors have at least one element and do not waste your computer time testing for that.
• You must not use vectors that are only declared, but have no allocated memory (see the description of VF_vector). If you did not switch off warnings, you may be warned also by the compiler not to do that ("possible use of xxx before definition").
• Constant parameters should not exceed 1.E32 for floats, 1.E150 for doubles, or 1.E2000 for long doubles. Normally, these ranges should suffice for any application...
• 16-bit Borland C++ only: Do not forget to write the line
  NEWMATHERR
  after the header into the module containing main(),  WinMain(), or OwlMain(), in order to maintain compatibility both with older and later versions of Borland C++ (see chapter 5.3.1).

Back to Table of Contents

6.2 Problems with Windows3.x?

• The background routines controlling intermediate results do not only work at the expense of your time, they may also at some point decide to load a NULL selector into the segment registers FS and GS. If you happen to use these registers (somehow, they were meant by Intel to be used!), Windows' answer on your next operation will be the familiar "General Protection Fault (Error 13)". Therefore, the Windows versions of OptiVec do not use FS and GS at all.
• If a floating-point multiplication or division happens to result in a so-called "denormal number" (see chapter 5.4), Windows at first accepts this result. The next time you use this denormal result, however, Windows decides that it had better been zero. Checking for zero by a comparison like
  if(x != 0.0)...
  yields the correct answer that x it is not zero, but, after (!) this check, Windows makes x exactly zero, if it is loaded onto the number stack. This leads to hard-to-find errors. If you inspect OptiVec routines with a debugger, you may at some points encounter strange, seemingly ineffecient code being used for comparisons. This is a fix for the described problem which costs time, but saves you from Windows- induced DIVIDE ERROR crashes.
• Related to the last problem is another "feature" of Windows3.x: after the comparison of two floats or two doubles, one of which is denormal, -NAN ("minus not-a-number") may appear on the number stack. Some time later, this leads to a "Floating-point invalid" or a "Stack Overflow" error – another means of killing your application. If you encounter -NAN on the number stack when debugging your programs (with or without VectorLib used), you should find out which comparison(s) caused the problem and add the line
  asm ffree ST(0);
  after this or these comparisons.

Back to Table of Contents

6.3 Problems with 32-bit Windows?

Back to Table of Contents

6.4 Problems with Borland's 16-bit Linker?

If you are still working with Borland (Turbo) C++ 3.x, you cannot simultaneously include VC??.LIB and MC??.LIB, as the linker is not able to handle these large libraries. As very few people are still using BC 3, we have discontinued full support for that compiler and do no longer offer the special BC 3 version OptiVec, previously fixing that problem by splitting the libraries up into many smaller ones. You still can extract the needed modules from the MC??.LIB libraries yourself, however, and include them as .OBJ nodes into your project.

Back to Table of Contents

---

7. The Include-Files and Units of OptiVec

C/C++ only: Declare the use of OptiVec functions with #include statements. If you are using MFC (Microsoft Foundation Classes) or Borland's OWL (ObjectWindows Library), the MFC or OWL include-files have to be #included before (!) the OptiVec include-files.

Pascal/Delphi only: Declare the use of OptiVec functions with the uses clause.
 

Include-file (add suffix .H) or unit	Contents
VecLib	Basic definitions of the data types along with the functions common to all data types (prefix V_) except for the graphics initialization functions.
VFstd, VDstd, VEstd	Floating-point "standard operations:" generation and initialization of vectors, index-oriented manipulations, data-type interconversions, statistics, analysis, geometrical vector arithmetics, Fourier-Transform related functions, I/O operations.
VCFstd, VCDstd, VCEstd, VPFstd, VPDstd, VPEstd	Standard operations for cartesian and polar complex vectors
VIstd, VBIstd, VSIstd, VLIstd, VQIstd	Standard operations for signed integer vectors
VUstd, VUBstd, VUSstd, VULstd, VUIstd	Standard operations for unsigned integer vectors (VUIstd only for C/C++)
VFmath, VDmath, VEmath	Algebraic, arithmetical and mathematical functions for floating-point vectors
VCFmath, VCDmath, VCEmath, VPFmath, VPDmath, VPEmath	Arithmetical and mathematical functions for complex vectors
VImath, VBImath, VSImath, VLImath, VQImath	Arithmetical and mathematical functions for signed integer vectors
VUmath, VUBmath, VUSmath, VULmath, VUImath	Arithmetical and mathematical functions for unsigned integer vectors (VUImath only for C/C++)
Vgraph	Graphics functions for all data types
VFNLFIT, VDNLFIT, VENLFIT	Non-linear fitting functions (Pascal/Delphi only; in C/C++, they are in M?std)
VFMNLFIT, VDMNLFIT, VEMNLFIT	Non-linear fitting functions for multiple data sets (Pascal/Delphi only; in C/C++, they are in M?std)
MFstd, MDstd, MEstd	Matrix operations for real-valued matrices
MCFstd, MCDstd, MCEstd	Matrix operations for cartesian complex matrices
Mgraph	Matrix graphics functions for all data types
MFNLFIT, MDNLFIT, MENLFIT	Non-linear fitting functions for Z = f(X, Y) data (Pascal/Delphi only; in C/C++, they are in M?std)
MFMNLFIT, MDMNLFIT, MEMNLFIT	Non-linear fitting functions for multiple Z = f(X, Y) data sets (Pascal/Delphi only; in C/C++, they are in M?std)
NEWCPLX	complex class library CMATH; C++ only
CMATH	complex library CMATH for Pascal/Delphi and plain C
CFMATH, CDMATH, CEMATH	C/C++ only: type-specific parts of CMATH.
XMATH	A few non-vectorized math functions needed internally by other OptiVec functions; they are publically accessible (see chapter 9). C/C++: declares also the sine, cosec, and tangent tables for VF_sinrpi2 etc.
FSINTAB2, DSINTAB2, ESINTAB3, FSINTAB3, DSINTAB3, ESINTAB3	sine tables (Pascal/Delphi only; for C/C++, they are in XMATH)
FCSCTAB2, DCSCTAB2, ECSCTAB3, FCSCTAB3, DCSCTAB3, ECSCTAB3	cosecant tables (Pascal/Delphi only; for C/C++, they are in XMATH)
FTANTAB2, DTANTAB2, ETANTAB3, FTANTAB3, DTANTAB3, ETANTAB3	tangent tables (Pascal/Delphi only; for C/C++, they are in XMATH)
VecObj	basic definitions for VecObj, the object-oriented interface for C++
fVecObj, dVecObj, eVecObj	VecObj member functions for real-valued vector objects (C++ only)
cfVecObj, cdVecObj, ceVecObj pfVecObj, pdVecObj, peVecObj	VecObj member functions for complex vector objects (C++ only)
iVecObj, biVecObj, siVecObj, liVecObj, qiVecObj	VecObj member functions for signed-integer vector objects (C++ only)
uVecObj, ubVecObj, usVecObj, ulVecObj, uiVecObj	VecObj member functions for unsigned-integer vector objects (C++ only)
OptiVec	includes the whole OptiVec package (C++ only)
VecAll	includes all VectorLib and CMATH functions (C or C++ only)
MatAll	includes all MatrixLib functions (C or C++ only)

 

Back to Table of Contents

---

E N D