OptiVec   Version 8 for C/C++,   Delphi and Lazarus
OptiCode Dr. Martin Sander Software Development Brahmsstr. 6 D-32756 Detmold Germany http://www.optivec.com e-mail: optivec@gmx.de	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 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 Demo 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 Demo-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.de/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 contrast to integrated packages like MatLab or others, OptiVec has the advantage of being incorporated into the modern and versatile languages C/C++ and Pascal/Delphi. Both 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, in 1996, the first product on the market offering a comprehensive vectorized-functions library realized in a true Assembler implementation – and has only grown and evolved since.

• 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 (or UComplex of Lazarus), 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

• Embarcadero / Borland / CodeGear C++ (all versions of RAD Studio and Borland C++ Builder; even Borland C++ versions back to 5.0 still work) for Win32 and Win64 (native Win32 / Win64 only; no .NET applications!).
• Microsoft Visual C++ (all versions of Microsoft Visual Studio and Visual C++ from the present down to Visual Studio 2005) both for 64-bit and for 32-bit Windows on PC platforms.
• GCC (always the current version) both for 64-bit and for 32-bit Windows on PC platforms.
• LLVM CLang (always the current version) both for 64-bit and for 32-bit Windows on PC platforms.
• Embarcadero / Borland Delphi, versions 12.x, 11.x, 10.x, XE Series, 2010, 2009, on 32-bit and 64-bit Windows
• Lazarus / FreePascal, exclusively for the 64-bit Windows platform.
• new: Linux with GCC or LLVM CLang (64-bit)

1. Demo Versions
   The Demo version contains only a selection of libraries:
   1. 64-bit: P8D (General-Purpose debug library, back-compatible to Core2 / AMD64) and
      P9M (automatic multi-threading; up-to-date processors required: Haswell+ / Excavator+).
   2. 32-bit: P4D: General-Purpose debug version, using the FPU for maximum floating-point accuracy, safety and widest processor compatibility range - down to 486DX / Pentium / Athlon.
      This version runs on all 32-bit Windows versions (including the 32-bit mode of 64-bit Windows).
   3. 32-bit: P8M: Multi-Core library for use on AMD64 x2, Core2 Duo or their multi-core successors. In addition to the automatic distribution of the work load over the available processor cores (auto-threading), the speed is also enhanced by employing SSE, SSE2, SSE3 etc. command sets for many floating-point operations. Be prepared, however, to accept a certain loss of accuracy as a consequence of the use of SSE commands. Overflow, singularity, and loss-of-precision errors are treated "silently" by setting the default result as indicated in the documentation of each function.
    
2. Full Registered Versions
   The libraries come in several versions of processor utilization:
   • P4  (widest processor compatibility range, down to 486DX / Pentium / Athlon for all 32-bit Windows versions)
   • P8  (min. Core2xxx or AMD64xxx)
     siginificantly faster through the use of SSE, SSE2, SSE3 commands.
   • P9  (at least Intel Core i 4th generation (Haswell), AMD Excavator)
     again siginificantly faster through the use of AVX, AVX2, and FMA3 instructions, at most so for "heavy-weight" functions. Beware: If used in an app consisting mostly of scalar calculations and "light-weight" vector functions like VF_addC, VF_round etc., some processors react on the AVX2 instructions with down-clocking, so that the overall performance may even get slower than with P8! Also, AMD processors generally profit much less from P9 than Intel-based systems, because Intel accords a higher priority to a fast 256 byte unit, whereas AMD rather devote their transistors to more processor cores than to ultra-fast floating-point.
   These versions are differentiated into sub-versions:
   • Normal Version:
     Optimized for smaller vectors / matrices with up to several 100 elements, calculations running in a single thread.
   • Debug Version with dimension-consistency checking:
     In order to prevent hard-to-track memory errors, possibly occurring through the violation of vector and matrix boundaries, this debug version checks all input vectors / matrices and their sizes for consistency. It is highly recommended to use the debug libraries during the debugging phase of application development and switch to the higher-performance versions only after you have made sure that no memory issues, as detected by the debug libraries, remain unsolved. Additionally, all overflow, singularity, and loss-of-precision errors lead to an error message. (In contrast to this Debug library, all other OptiVec library versions treat these errors silently by setting the result to the default value indicated in the documentation.)
   • Multi-Processor Version:
     For larger vectors and matrices, the work load can be distributed among several processor cores. Thereby, the performance can theoretically be multiplied by the number of available processor cores. The Multi-Processor version initiates additional worker threads which, in turn, are attributed to the processor units by the operating system. Every function checks if the work can reasonably be distributed (auto-threading).
     The decision, if the multi-processor version should be employed, strongly depends on the nature of the desired calculations. The reason lies in the inter-thread communication "bureaucracy" involved in the auto-threading mechanism. Only from a certain vector / matrix size on, these overhead losses can be earned back. For the transcendental functions of complex arguments, this is the case already at vector lengths of 60-80 elements, whereas, for a function like VF_addV, the performance scales with the number of processors only from about 10,000 elements on. Normally, the decision between the normal and the multi-processor version will be made just by trying both.
     An application, linked with the multi-processor library, runs without problems on a single-processor computer. However, the speed will typically be 10-20% slower than with the normal library.
   • CUDA Version (Windows only):
     This is a multi-processor version which goes even one step further: It checks, if processing of large vectors / matrices can be outsourced to a CUDA device. In order to use this library version, you must have a CUDA-enabled NVIDIA graphics card (or dedicated hardware like Tesla, Fermi, or Kepler board) installed in your computer. Be sure also visit www.nvidia.com to download and install the latest driver for your graphics card. On the positive side, even a sub−100$ graphics card can speed up certain operations by an amazing factor of 10. There are drawbacks, however: Getting this version up and running is not always trivial, so we recommend this version only for use on your own computer (not for applications distributed for others).

Specifics of the OptiVec versions for the different compilers

• Embarcadero / Borland / CodeGear C++:
  You have to include two libraries: a base-library, specific for the compiler version and configuration, and a processor-specific library. For example, for the classic bcc32 compiler with static BC++ run-time library and with widest processor compatibility, you would link VCFS.LIB + VCF4W.LIB. For details, see chapter 1.4.
• Microsoft Visual C++:
  The Demo version comes with libraries for "multi-thread debug", and "multi-thread DLL debug". The full (registered) version contains additional libraries for the corresponding release runtimes. As each version of Visual Studio comes with its own runtime DLL, OptiVec contains version-specific libraries to be used only with Visual Studio 2022, 2019, 2017, and so on, down to 2005.
• GCC and LLVM CLang (Windows):
  In contrast to the conditions for the commercial compilers, we provide the Community with the OptiVec 32-bit P4D library and the 64-bit P8D library for the free compilers as Freeware.
  Only GCC: Both for 32-bit and for 64-bit, the standard configurations of GCC are covered by individual OptiVec base libraries, i.e. for Windows or Posix threads, and for each of those, the selection between SEH, Dwarf, or Setjmp-Longjmp exceptions.
• GCC and LLVM CLang (Linux):
  Again, the P8D library is Freeware.
  Single-thread and multi-thread applications need different OptiVec base libraries: ovlxcbase64s.a or ovlxcbase64m.a, respectively.
• Delphi:
  Each Delphi release requires its own OptiVec library version.
• Lazarus:
  All OptiVec routines are cdecl. This means their names are case-sensitive, and you have to write them exactly as in the documention. The technical reason for this is that, in the other calling models, Lazarus decorates all function names with encoded type information. So the OptiVec function names would not be found in the included *.o files.

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 even on modern PCs with their modest 2, 4 or 8-processor core configurations. Consequently, at first sight, it might seem difficult 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 automatically 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.

1.1.1 General OptiVec Optimization Strategies

Here are the most important optimization strategies, employed in OptiVec to boost the performance on any PC (regardless of the number of processor cores):

Preload of constants
Floating-point as well as integer constants, employed in the evaluation of mathematical functions, are loaded into registers 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.

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 wasted waiting for them when they are actually needed.

Full XMM and FPU stack usage
Where necessary, all eight (64-bit: all sixteen) XMM registers and/or all eight coprocessor registers are employed.

Use of SIMD commands
You might wonder why this strategy is not listed first. The SSE or "Streaming Single-Instruction-Multiple-Data Extensions", introduced since the days of the Pentium III and improved with every new processor generation, provide explicit support for vectorized programming with floating-point data in float / single or double precision. At first sight, therefore, they should revolutionize vector programming. Given the usual relation between processor and data bus speeds, however, many of the simple arithmetic operations are 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 many cases, the advantage of using an SIMD instruction instead of separate FPU instructions 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. Please note, however, that, the SIMD-employing library versions (P8, P9 etc.) generally sacrifice 1-2 digits of accuracy in order to attain the described speed gain. If this is not acceptable for your specific task, please stay with the P4 libraries.

Superscalar scheduling
By careful "pairing" of commands whose results do not depend upon each other, the parallel integer pipes and fadd/fmul units of the processor are used as efficiently as possible.

Loop-unrolling
Where SIMD instructions cannot be used and 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 execution pipes. 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.

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. There is also a brute-force approach to precision-control: 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 slightly sped up from Pentium CPUs on. Be, however, prepared to accept even lower-than-single accuracy of your end results, if you elect this option. For further 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 modern processors uses 64-byte lines. 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). 32-bit compilers align the stack on 4-byte boundaries, which means there is a certain chance that the 8 bytes of a double or the 10 bytes of an extended, stored on the stack, will cross a cache-line 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), 16-byte (for extendeds), or 64-byte boundaries (for XMM and YMM values).

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.

1.1.2 Multi-Processor Optimization

Multithread support
Modern multi-core processors allow the operating system to distribute threads among the available processors, scaling the overall performance with the number of available processor cores. 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 are reentrant and may run in parallel.

When designing your multi-thread application, you have two options: functional parallelism and data parallelism.

Functional Parallelism
If different threads are performing different tasks – they are functionally different – one speaks of functional parallelism. As an example, consider one thread handling user input / output, while another one performs background calculations. Even on a single-core CPU, this kind of multi-threading may offer advantages (e.g., the user interface does not block during extensive background calculations, but still takes input). On a multi-core computer, the two (or more) threads can actually run simultaneously on the different processor cores. In general, however, the load balance between the processor cores is far from perfect: often, one processor is running at maximum load, while another one is sitting idle, waiting for input. Still, functional multithreading is the best option whenever your numerical tasks involve vectors and matrices of only small-to-moderate size.

Data Parallelism
In order to improve the load balance between the available processor cores, thereby maximizing throughput, it is possible to employ classical parallel processing: the data to be processed is split up into several chunks, each thread getting one of these chunks. This is aptly called data parallelism. The usefulness of this approach is limited by the overhead involved in the data distribution and in the thread-to-thread communication. Moreover, there are always parts of the code which need to be processed sequentially and cannot be parallelized. Therefore, data parallelism pays off only for larger vectors and matrices. Typical break-even sizes range from about 100 (for the calculation of transcendental functions of complex input values) to several 10,000 elements (as in the simple arithmetic functions). Only when your vectors and matrices are considerably larger than that threshold, the performance is actually improved over a functional-parallelism approach. The boost then quickly approaches (but never exactly reaches) the theoretical limit of a factor equal to the number of processor cores available.

1.1.3 CUDA Device Support

• Obviously, the cudaOptiVec libraries can be used only with a CUDA-enabled device installed. This means, only NVIDIA products are supported.
• Already a sub−100$ graphics card can boost the performance of certain functions on a computer with a medium-range CPU by a factor of 10, dedicated hardware by much more. However, the combination of a high-end CPU with a low-end graphics card (as it is often found in laptop computers) will only marginally benefit from the cudaOptiVec libraries.
• The cost of swapping data forth and back between main-board memory and graphics memory is so high that it can be "earned" back only for quite large vectors and matrices. E.g., for mathematical functions like the sine or exponential functions, CUDA pays off only from several 1,000 vector elements on.
• Using CUDA with OptiVec can be as easy as simply linking with the cudaOptiVeclibraries instead of the standard OptiVec libs. No modifications of your source code are necessary at this stage.
• If you are willing to modify your source code, however, there are, ways to greatly improve performance over this most simple approach. To this end, the cudaOptiVec libraries offer various sets of functions, distinguished by their prefixes:
  • VF_, VFx_ etc. (the "normal" prefixes): Automatic use of the CUDA device. All OptiVec functions check if using the CUDA device makes sense and decide accordingly wether to source-out processing to the graphics processor or to stay on the CPU. This decision mechanism is far from perfect, as it cannot easily "know" how good your graphics card is in relation to your CPU.
  • VFcu_, VFxcu_, etc. (add "cu" to the original prefix, right before the underbar): Forced use of the CUDA device. Use of these prefixes makes most sense if you switch off the automatic mechanism by calling V_setAutoCudaUse( 0 );
  • cudaVF_, cudaVFx_, etc. (prepend the original prefix by "cuda"): Work on the CUDA device, processing vectors / matrices which have already been transferred into device memory (or into pinned host memory). In order to use these prefixes, you have to manage the memory transfers yourself. cudaOptiVec offers the necessary interface functions to do that.
• NVIDIA has terminated support for 32-bit. Therefore, the 32-bit cudaOptiVec libraries had to be created with the old CUDA v8.0, whereas the 64-bit cudaOptiVec libraries are always based on the latest CUDA version. In one of the next releases, the 32-bit libraries will have to be given up altogether.
• NVIDIA might at any time change the licence terms for their CUDA libraries. While we do expect NVIDIA to maintain their open policy, there can be no guarantee as to permanent support of CUDA by OptiVec.
• For a step-by-step introduction into using OptiVec for CUDA, see CudaOptiVec.HTM

1.1.4 Choosing the right OptiVec Library

For large vectors/matrices on multi-core machines, multi-core optimized libraries actively distribute the work load over the available processor cores for data parallel execution. These libraries are marked by the letter "M", as in  OVVC8M.LIB  (for MS Visual C++, using SSE2),  VCF4M.LIB  (for Embarcadero/Borland C++, full FPU accuracy),  or the units in OPTIVEC\LIB8M  (for Delphi, using SSE3). These libraries are designed for AMD 64 x2,    Intel Core2 Duo, or machines equipped with several discrete processors of the Pentium 4+ level. The CUDA libraries are based on the "M" libraries and are marked by the letter "C", as, e.g., in  OVVC8C.LIB.
The "M" and "C" libraries will still run on single-core machines, but – due to the thread-management overhead – somewhat slower than the general-purpose libraries. Although the "M" libraries are designed with medium to large vectors in mind, the penalty for using them with smaller vectors is almost negligible, as the OptiVec thread-engine automatically executes a function in a single thread, if the vector size is too small for parallel execution to earn back the cost involved in the thread-to-thread communication.
If you use the "M" or "C" libraries, your programme must call V_initMT( nAvailProcCores ) before any of the vector functions.

Back to Table of Contents

1.2 Licence Terms for the Demo Version

1. You may test the SOFTWARE free of charge for a period of up to 90 days on one computer.
2. Applications, created with the Demo version of this SOFTWARE, will run only on the same computer on which this SOFTWARE has been installed. They cannot and may not be distributed to others. After the end of the trial period, they will cease functioning.
3. If you want to continue using this SOFTWARE after testing, and/or if you wish to distribute programs containing functions of this SOFTWARE, you have to purchase the registered version (see chapter 1.3).
4. Special conditions apply for the 32-bit P4D and the 64-bit P8D library for GCC and for LLVM CLang: These libraries are Freeware. You can use them free of charge for as long as you wish, both for non-commercial and commercial applications. Applications, created with these libraries, may be distributed free of restrictions to others.
5. This SOFTWARE is provided on an "as is" basis. Any explicit or implicit warranties for the SOFTWARE are excluded.
6. Despite thorough testing of the SOFTWARE, errors and bugs cannot be excluded with certainty. No claims as to merchantability or fitness for a particular purpose are made.
7. You may not use the SOFTWARE in any environment or situation where personal injury or excessive damage to anyone's property (including your own) could arise from malfunctioning of the SOFTWARE.
8. You may not decompile, disassemble, or otherwise reverse engineer the SOFTWARE into a machine-readable form. You may, however, inspect the functions it contains by means of debuggers like those included in the Borland and Microsoft compilers.

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.

Price List

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 order through www.optivec.de/order/
or send this order form to

OptiCode – Dr. Martin Sander Software Dev.
Brahmsstr. 6
D-32756 Detmold
Germany
optivec@gmx.de

Back to Table of Contents

1.3.2 License Terms for the Registered version

The SOFTWARE in this package is licensed to you as the user. It is not sold. The term "user" means a programmer who links binary code of this SOFTWARE into his own applications. Those people using, in turn, his applications without the need of installing this SOFTWARE themselves, do not need any runtime license for the SOFTWARE. The right to distribute applications containing code of this SOFTWARE is included in the license fee for the commercial version.

Once you have paid the required license fee, you may use the SOFTWARE for as long as you like, provided you do not violate the copyright and if you observe the following rules:

1. You may use the SOFTWARE on any computer for which it is designed, as long as not more than one person uses it at any time.
   
2. You may make backup copies of the SOFTWARE for your personal use. You may only transfer the SOFTWARE to somebody else if you transfer the original and all copies, retaining no copies for yourself. You may not lease or rent the SOFTWARE to others.
   
3. You may not decompile, disassemble, or otherwise reverse engineer the SOFTWARE into a machine-readable form. You may, however, inspect the functions contained in this SOFTWARE by means of debuggers like those included in the Borland and Microsoft compilers.
   
4. If you payed the reduced licence fee for the "educational version" rather than the full rate for the "commercial version", the use of this SOFTWARE is restricted to private and educational purposes. In this case, you may not use the SOFTWARE for commercial purposes or for government purposes other than education.
   Applications using functions of this SOFTWARE may be freely distributed (i.e. without any run-time licence) only if created with the "commercial edition" and on condition that the functions of this SOFTWARE are permanently linked into a program etc., but do not appear as a library to the user of that application.
   
5. You may not use the SOFTWARE in any environment or situation where personal injury or excessive damage to anyone's property (including your own) could arise from malfunctioning of the SOFTWARE.
   
6. OptiCode's liability is limited by the enclosed Limited Warranty. In no case shall OptiCode's liability exceed the license paid for the right to use the SOFTWARE.

1. OptiCode warrants that the magnetic or optic media on which the SOFTWARE is recorded are free from defects in materials and workmanship under normal use. The SOFTWARE itself will perform substantially in accordance with the specifications set forth in the documentation.
   
2. The above express warranties are made for a period of six months from the date the SOFTWARE is delivered to you as the first user.
   
3. Any magnetic/optic or printed media from this package proving defective in materials or workmanship will be replaced on an exchange basis.
   
4. Great care has been taken to ensure that the SOFTWARE operates in accordance with the specifications as described in the documentation. However, it is not guaranteed that this SOFTWARE will operate completely free of errors or that the documentation is free of errors.
   
5. Any implied warranties including any warranties of merchantability or of fitness for a particular purpose are limited to the terms of the above express warranties.
   
6. OptiCode shall not in any case be liable for special, incidental, consequential, indirect or other damages arising from any breach of these warranties or of the license conditions, even if he has been notified of the possibility of such damages.

Back to Table of Contents

1.4 Getting Started

1.4.1 OptiVec for C++ Builder (Embarcadero / Borland C++)

Second, select the required processor-specific library from the following table and add it to your project. Here, there is no difference between the classic and the CLang-enhanced compiler.
 

Platform	Compiler	Processor	General-purpose	Debug	Multi-Processor	MP+CUDA
Win64x	bcc64x	P9: Haswell+ / Excavator+	OVVC64x_9.lib	----	OVBC64x_9M.lib	OVBC64x_9C.lib
	bcc64x	P8: AMD64xxx, Core2xxx	OVBC64x_8.lib	OVBC64x_8D.lib	OVBC64x_8M.lib	OVBC64x_8C.lib
Win64	bcc64	P9: Haswell+ / Excavator+	OVVC64_9.a	----	OVBC64_9M.a	OVBC64_9C.a
	bcc64	P8: AMD64xxx, Core2xxx	OVBC64_8.a	OVBC64_8D.a	OVBC64_8M.a	OVBC64_8C.a
Win32	bcc32 (classic)	P8: AMD64xxx, Core2xxx	VCF8W.LIB	----	VCF8M.LIB	VCF8C.LIB
		P4: Max compatibility, full FPU accuracy	VCF4W.LIB	VCF4D.LIB	VCF4M.LIB	----
	bcc32c (CLang) from C++ Builder 10.1 Berlin on	P8: AMD64xxx, Core2xxx	ovbc32c_8.lib	----	ovbc32c_8m.lib	ovbc32c_8c.lib
		P4: Max compatibility, full FPU accuracy	ovbc32c_4.lib	ovbc32c_4d.lib	ovbc32c_4m.lib	----
	bcc32c (CLang) up until C++ Builder 10 Seattle	P8: AMD64xxx, Core2xxx	VCF8W.LIB	----	VCF8M.LIB	VCF8C.LIB
		P4: Max compatibility, full FPU accuracy	VCF4W.LIB	VCF4D.LIB	VCF4M.LIB	----

 
The libraries for multi-processor systems run on workstations with discrete processors, as well as on multi-core processors like AMD64x2, Core2 Duo and so on.

In order to profit from the CUDA-enhanced OptiVec library, do the following things:

1. In addition to the OptiVec base library selected above, include the base import library OVBCCU32.lib (32-bit), OVBCCU64.lib (Win64x), OVBCCU64.a (Win64, up-to-date CUDA devices), or OVBCCULEG64.lib (Win64x) / OVBCCULEG64.a (Win64, legacy CUDA devices with comp.cap. 3.5, 5.0, 6.0).
2. Make sure the corresponding DLL, OVBCCU32.DLL, OVBCCU64.DLL, or OVBCCULEG64.DLL is either in the same directory as the executable you are about to create, or in another directory contained in the Windows environment variable PATH.
3. Include the processor-specific OptiVec library, ending with the letter "C", e.g. VCF8C.LIB or OVBC64_8C.lib.

In previous versions, there were certain restrictions concerning the use of CMATH with the 32-bit CLang-enhanced Borland Compiler bcc32c.exe. All of them have now been lifted.

Continue with chap. 1.5 Declaration of OptiVec functions in C/C++

1.4.2 OptiVec for Visual C++ (Microsoft Visual Studio)

Please note that there is a certain inconsistency in the description of the configurations in Visual Studio: The default configurations "Debug" and "Release" actually use the runtime library and MFC as DLL. Therefore, you have to use the OptiVec base libraries OVVC??MDD.lib and OVVC??MDR.lib with these configurations. There is a problem with using these configurations, however: you always need the RTL and MFC DLL's for the specific compiler version installed on your computer. For many applications, it is therefore recommended to change Project / Properties / Configuration Properties / C/C++ / Code Generation / Runtime Library into "Multi-Thread Debug (/MTd)" or "Multi-Thread Release (MT)", respectively, in order to get rid of the DLL redistributables. This is done in the "DebugStatic" configuration in the demo files coming with OptiVec.

After that, please add the second, processor-specific OptiVec library according to the following table:

Processor	General-purpose library	Debug library	Multi-Processor	MP + CUDA	64-bit General	64-bit Debug	64-bit Multi-Proc.	64-bit MP + CUDA
P9: Haswell+ / Excavator+	----	----	----	----	OVVC64_9.LIB	----	OVVC64_9M.LIB	OVVC64_9C.LIB
P8: AMD64xxx, Core2xxx	OVVC8.LIB	----	OVVC8M.LIB	OVVC8C.LIB	OVVC64_8.LIB	OVVC64_8D.LIB	OVVC64_8M.LIB	OVVC64_8C.LIB
P4: Full FPU accuracy, 486DX/Pentium	OVVC4.LIB	OVVC4D.LIB	OVVC4M.LIB	----	----	----	----	----

 
The libraries for multi-processor systems run on workstations with discrete processors, as well as on multi-core processors like AMD64x2, Core2 Duo and so on.
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 / (Configuration) Settings / Linker / Input / Object and Library Modules must contain user32.lib. Otherwise you would get the linker error "error LNK2001: Unresolved external symbol __imp__MessageBoxA@??".
 

In order to profit from the CUDA-enhanced OptiVec library, do the following things:

1. In addition to the OptiVec base library selected above, include the base import library OVVCCU32.lib (32-bit), OVVCCU64.lib (64-bit, up-to-date CUDA devices), or OVVCCULEG64.lib (64-bit, legacy CUDA devices with comp.cap. 3.5, 5.0, 6.0).
2. Make sure the corresponding DLL, OVVCCU32.DLL, OVVCCU64.DLL, or OVVCCULEG64.DLL is either in the same directory as the executable you are about to create, or in another directory contained in the Windows environment variable PATH.
3. Include the processor-specific OptiVec library, ending with the letter "C", e.g. OVVC8C.LIB or OVVC64_8C.lib.

Continue with chap. 1.5 Declaration of OptiVec functions in C/C++

1.4.3 OptiVec for GCC (GNU Compiler Collection) on Windows

You have to include two OptiVec libraries. The first one ("base library") contains the interface between OptiVec and the GCC runtime libraries; it has to be matched with the specific configuration of GCC. The second one is independent from the configuration and runtime library; you have to choose it according to the desired CPU support.
First choose the base library from the following table:
 

Platform	GCC thread model	GCC exception model	Matching OptiVec base library
Win64	Windows threads	SEH	ovgcbase64ws.lib
	Windows threads	Setjmp/Longjmp	ovgcbase64wj.lib
	Posix threads	SEH	ovgcbase64ps.lib
	Posix threads	Setjmp/Longjmp	ovgcbase64pj.lib
Win32	Windows threads	Dwarf	ovgcbase32wd.lib
	Windows threads	Setjmp/Longjmp	ovgcbase32wj.lib
	Posix threads	Dwarf	ovgcbase32pd.lib
	Posix threads	Setjmp/Longjmp	ovgcbase32pj.lib

After that, choose the second, processor-specific OptiVec library according to the following table:

Processor	32-bit General-purpose	Debug	Multi-Processor	MP + CUDA	64-bit General	64-bit Debug	64-bit Multi-Proc.	64-bit MP + CUDA
P9: Haswell+ / Excavator+	----	----	----	----	ovgc64_9.lib	----	ovgc64_9m.lib	ovgc64_9c.lib
P8: AMD64xxx, Core2xxx	ovgc32_8.lib	----	ovgc32_8m.lib	ovgc32_8c.lib	ovgc64_8.lib	ovgc64_8d.lib	ovgc64_8m.LIB	ovgc64_8c.lib
P4: Full FPU accuracy, 486DX/Pentium	ovgc32_4.lib	ovgc32_4d.lib	ovgc32_4m.lib	----	----	----	----	----

 
The libraries for multi-processor systems run on workstations with discrete processors, as well as on multi-core processors like AMD64x2, Core2 Duo and so on.

In order to profit from the CUDA-enhanced OptiVec library, do the following things:

1. In addition to the OptiVec base library selected above, link with ovgccu32.dll (32-bit), ovgccu64.dll (64-bit, up-to-date CUDA devices), or ovgcculeg64.dll (64-bit, legacy CUDA devices with comp.cap. 3.5, 5.0, 6.0). In contrast to other compilers, GCC can directly link with DLL's, creating its import library "on the fly"; so you do not need to provide a separate import library.
2. Make sure these DLL's are either in the same directory as the executable you are about to create, or in another directory contained in the Windows environment variable PATH.
3. Include the processor-specific OptiVec library, ending with the letter "C", e.g. ovgc32_8c.lib or ovgc64_8c.lib.

One very important point to observe when working with GCC is that the linker does not resolve inter-dependencies between included libraries. As the base library and the processor-specific library of OptiVec do have interdependencies, this means that you will have to include them pair-wise at least twice. In each pair, the processor-specific library should come first and the base library second. If you get linker errors about missing OptiVec functions, just include the same pair of libraries once more. For an example, see the makefile for the OptiVec demo programs.

GCC is the only of the "big" compilers to support 80-bit real numbers (long doubles, extended) in 64-bit. This is a very valuable feature, as the extra accuracy and range can make life much simpler on many occasions. OptiVec also supports this data type with the VE_, VCE_, VPE_, ME_, and MCE_ functions.

For the GCC-Linux version of OptiVec for GCC, see below.

Continue with chap. 1.5 Declaration of OptiVec functions in C/C++

1.4.4 OptiVec for LLVM CLang on Windows

You have to include two OptiVec libraries. The first one ("base library") contains the interface between OptiVec and the CLang runtime libraries. (Actually, CLang heavily relies on the Visual C++ runtime libraries and is almost compatible with Visual C++. This "almost" compatibility, however, is not perfect, to the point that OptiVec has to come with an individual CLang version.) This base library is ovclbase64.lib for 64-bit and ovclbase32.lib for 32-bit.

The second library is specific to the desired CPU support:
 

Processor	32-bit General-purpose	Debug	Multi-Processor	MP + CUDA	64-bit General	64-bit Debug	64-bit Multi-Proc.	64-bit MP + CUDA
P9: Haswell+ / Excavator+	----	----	----	----	ovcl64_9.lib	----	ovcl64_9m.lib	ovcl64_9c.lib
P8: AMD64xxx, Core2xxx	ovcl32_8.lib	----	ovcl32_8m.lib	ovcl32_8c.lib	ovcl64_8.lib	ovcl64_8d.lib	ovcl64_8m.LIB	ovcl64_8c.lib
P4: Full FPU accuracy, 486DX/Pentium	ovcl32_4.lib	ovcl32_4d.lib	ovcl32_4m.lib	----	----	----	----	----

 
The libraries for multi-processor systems run on workstations with discrete processors, as well as on multi-core processors like AMD64x2, Core2 Duo and so on.

In order to profit from the CUDA-enhanced OptiVec library, do the following things:

1. In addition to the OptiVec base library selected above, link with ovvccu32.lib (32-bit), ovvccu64.lib (64-bit, up-to-date CUDA devices), or ovvcculeg64.lib (64-bit, legacy CUDA devices down to comp.cap. 3.5). Note that this is no typo: Here, the libraries of cudaOptiVec for Visual C++ are used also for CLang.
2. Make sure the corresponding DLL's are either in the same directory as the executable you are about to create, or in another directory contained in the Windows environment variable PATH.
3. Include the processor-specific OptiVec library, ending with the letter "C", e.g. ovcl32_8c.lib or ovcl64_8c.lib.

For the Linux-CLang version of OptiVec, see below.

Continue with chap. 1.5 Declaration of OptiVec functions in C/C++

1.4.5 OptiVec for Delphi

Continue with chap. 1.5.2 Declaration of OptiVec functions in Pascal / Delphi

1.4.6 OptiVec for Lazarus / FreePascal

Continue with chap. 1.5.2 Declaration of OptiVec functions in Pascal / Delphi

1.4.7 OptiVec for Linux with GCC or CLang

After that, choose the second, processor-specific OptiVec library according to the following table:

Processor	General	Debug	Multi-Proc. auto-threading
P9: Haswell+ / Excavator+	ovlxc64_9.a	----	ovlxc64_9m.a
P8: AMD64xxx, Core2xxx	ovlxc64_8.a	ovlxc64_8d.a	ovlxc64_8m.a

 
The libraries for multi-processor systems run on workstations with discrete processors, as well as on multi-core processors like AMD64x2, Core2 Duo and so on. They can only be used together with the base library ovlxcbase64m.a and need to be linked with the linker option -lpthread.

One very important point to observe when working with GCC and CLang on Linux is that the linker does not resolve inter-dependencies between included libraries. As the base library and the processor-specific library of OptiVec do have interdependencies, this means that you will have to include them pair-wise at least twice. In each pair, the processor-specific library should come first and the base library second. If you get linker errors about missing OptiVec functions, just include the same pair of libraries once more. For an example, see the makefile for the OptiVec demo programs.

1.5 Declaration of OptiVec functions

1.5.1 Declare the use of OptiVec functions in C/C++

Continue with chap. 1.6 Sample programs

1.5.2 Declare the use of OptiVec functions in Pascal / Delphi

1.6 Sample programs

• Microsoft Visual C++:
  Depending on the Visual Studio version: VDEMO_VS2019.sln, VDEMO_VS2013.sln and so on.
  Depending on the exact version, Visual Studio may have to convert this project map and its parts into a newer format. When prompted, answer "Yes to all" to accept this automatic conversion.
• Embarcadero / Borland C++:
  12.x, 11.x, 10.x, XE3 or higher: Open the project group VDEMO.groupproj (both 64-bit and classic Borland 32-bit compiler) or VDemo_BCC32C.groupproj (Clang-enhanced compiler BCC32C; 32-bit only)
  Alternatively (for older versions: always) open the individual projects:
  VDEMO.cbproj,   FITDEMO.cbproj,  MANDEL.cbproj are projects for RAD Studio 2009, 2010, XE, XE2
  The *.bdsproj projects are for BDS 2006 and 2007
  VDEMOB6.BPR, FITDEMOB6.BPR, and MANDELB6.BPR are for BC++ Builder 6+.
• GCC on Windows:
  The make file "makefile." contains the five targets VDemo, VSpeedDemo, FitDemo, Mandel, and CDemo. It is intended for use with GNU make. Before calling make, you may need to enter the path to the GCC compiler in the makefile.
• LLVM CLang:
  Although, in principle, CLang should be able to link with and call the Windows DLL's like GDI32.DLL, this appears not to work with the current releases. As all OptiVec demo programs rely on graphics output to visualize results, they are not available until this CLang glitch will be fixed. Consequently, the make file "makefile." contains only the three targets VSpeedDemo, FitDemo, and CDemo.
• Delphi:
  Open the project group VDemoD.groupproj. It contains the projects VDEMO.dproj, VSpeedDemo.dproj, FITDEMO.dproj, CDEMO.dproj, and MANDEL.dproj
• Lazarus / FreePascal:
  Open VDemo.lpi, VSpeedDemo.lpi, FitDemo.lpi, CDemo.lpi, or MANDEL.lpi.
• Linux with GCC or CLang:
  The make file "makefile." contains the three targets VSpeedDemo, FitDemo, and CDemo (case-sensitive!).

After these preparations, all OptiVec functions are available for your programs.
Should you wish to remove OptiVec from your computer, please run UNINSTAL.EXE or simply delete the directory OPTIVEC with its subdirectories.

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) is called quad (for "quadword integer") in OptiVec.
In 32-bit, the type quad is always signed. Functions for unsigned 64-bit integers are available only in the 64-bit versions of OptiVec.

• Borland C++ below C++ Builder 2006 only: For the 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 all 64-bit compilers (Visual C++ even not for 32-bit) do not support 80-bit reals, we define "extended" as "double" in the OptiVec versions for these compilers.
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. In the future, high-precision 128-bit real numbers (__fp128 / __float128) would find their place in this series as "G" for "great" and half floats (__fp16) as "H".

b) Pascal/Delphi only:

For historical reasons (dating back to the development of Turbo Pascal), the various integer data types have a somewhat confusing nomenclature in Delphi. In order to make the derived function prefixes compatible with the C/C++ versions of OptiVec, we define a number of synonyms, as described in the following table:

type	Delphi 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	Int64	QuadInt	VQI_
64 bit unsigned (x64 version only!)	UInt64	UQuad	VUQ_
16/32 bit signed	Integer		VI_
16/32 bit unsigned	Cardinal	UInt	VU_

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, uqVector, 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 uquad * uqVector 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; type uqVector = ^UQuad;

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.

 
Delphi also offers 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	Debug libraries: automatic; Release libraries: none	automatic with built-in size information
dynamic allocation	function VF_vector,  VF_vector0	procedure SetLength
initialization with 0	optional by calling VF_vector0	always
de-allocation	function V_free,  V_freeAll	procedure Finalize
reading single elements	function VF_element: a := VF_element(X,5); typecast into array also possible: a := fArray(X)[5];	index in brackets: a := X[5];
setting single elements	function VF_setElement: VF_setElement(X,5, a); Delphi only: typecast into array also possible: fArray(X)[5] := a;	index in brackets: X[5] := a;
getting the address of a single element	function VF_Pelement
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).

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_,  VUQ_, and VUI_

For the unsigned integer data types, we have:
prefix VUB_: data type unsigned char (unsigned byte) / UByte,
prefix VUS_: data type unsigned short / USmall,
prefix VU_: data type unsigned / UInt,
prefix VUL_: data type unsigned long / ULong (32-bit for Windows, 64-bit for Linux),
prefix VUQ_: data type uquad / UQuad (only for Win64 and Linux),
prefix VUI_: data type ui.

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 Embarcadero / 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 exists 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:

• 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. Again the same advice holds: 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 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
VCF_Reequ0	set all real parts equal to 0, leaving the imaginary parts unchanged
VCF_Imequ0	set all imaginary parts equal to 0, leaving the real parts unchanged
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.
VUI_ramp	"index ramp": Xi = i  (VUI_ and VU_ versions only)
VF_randomLC	high-quality random numbers
VF_random	simplified form of VF_randomLC for high-quality random numbers
VF_noiseLC	white noise
VF_noise	simplified form of VF_noiseLC fo white noise
VF_comb	"comb": equals a constant C at equidistant points, elsewhere 0

 

The following functions are used to access and modify single vector elements: 

VF_Pelement	returns a pointer to the vector element specified by its index
VF_element	returns a specific vector element
VF_getElement	copies a specific vector element into a variable
VF_setElement	sets a vector element to a new value
VF_accElement	X[i] += c; adds a value to one vector element
VF_decElement	X[i] -= c; subtracts a value from one vector element

 
The following functions generate windows for use in spectral analysis: 

VF_Hann	Hann 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

As a second possibility, the indices of conforming elements can be stored in an index vector as is done by the VF_cmp_...ind series. Some examples:
 

VF_cmp_neCind	Indices of all elements Xi != C
VD_cmp_lt0ind	Indices of all elements Xi < 0
VE_cmp_geVind	Indices of all elements Xi ≥ Yi

Testing if elements fall into a certain range is done by the functions with the postfixes "inclrange0C", "inclrangeCC", "exclrange0C" and "exclrangeCC":
 

VF_cmp_inclrange0C	TRUE for 0 ≤ x ≤ C (C positive), 0 ≥ x ≥ C (C negative)
VF_cmp_exclrange0C	TRUE for 0 < x < C (C positive), 0 > x > C (C negative)
VF_cmp_inclrangeCC	TRUE for CLo ≤ x ≤ CHi
VF_cmp_exclrangeCC	TRUE for CLo < x < CHi
VF_cmp_inclrange0Cind	Indices of all elements 0 ≤ Xi ≤ C  (C positive),   0 ≥ Xi > C  (C negative)
VF_cmp_exclrange0Cind	Indices of all elements 0 < Xi < C  (C positive),   0 > Xi > C  (C negative)
VF_cmp_inclrangeCCind	Indices of all elements CLo ≤ Xi ≤ CHi
VF_cmp_exclrangeCCind	Indices of all elements CLo < Xi < CHi

Counting elements fulfilling a comparison condition is performed by the VF_cnt_... series of functions. Some examples:
 

VF_cnt_eq0	count the number of elements equal to 0 (accepting −0 as valid)
VD_cnt_gtC	count the number of elements greater than a constant C
VE_cnt_leV	count the number of elements less than or equal to the corresponding elements of another vector
VLI_cnt_inclrange0C	count the number of elements xi falling into the range 0 ≤ xi ≤ C or, if C is negative, 0 ≥ xi ≥ C

Additionally, the signum function can be performed with the three possible answers +1 for "greater than", 0 for "equal to" or −1 for "less than". For input vectors of the unsigned integer data types, the output vectors are of the corresponding signed integer types.

VF_cmp0	signum function: compare to 0: yi = +1, if xi > 0; yi = 0, if xi = 0; yi = −1, if xi < 0.
VU_cmpC	compare to a constant C: yi = +1, if xi > C; yi = 0, if xi = C; yi = −1, if xi < C.
VE_cmpV	compare corresponding vector elements: zi = +1, if xi > yi; zi = 0, if xi = yi; zi = −1, if xi < yi

 
If you want to know only if one or more given values can be found at all in a table (but need neither the exact number nor position of occurrences), use one of the following functions: 

VF_iselementC	returns TRUE, if C is an element of a vector
VF_iselementV	checks for each element of a vector if it is contained in a table

Back to Table of Contents 

4.6.3 Direct Bit-Manipulation

Back to Table of Contents

4.6.4 Basic Arithmetics, Accumulations

The 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_flushInv	set all values to zero which are below a preset threshold and take the inverse of all other values
VF_absHuge	replace negative poles by positive ones
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

Again only within the floating-point data-types, you can also accumulate squares and products:

VF_accV2	fVector Y += fVector X2
VD_accVF2	dVector Y += fVector X2
VCF_accVmulVconj	cfVector Y += cfVector X * cfVector Y*

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. 

To determine the center of gravity of a vector, you have the choice between the following two functions:
 

VF_centerOfGravityInd	center of gravity, returned as an interpolated element index
VF_centerOfGravityV	center of gravity of a Y vector with explicitly given X axis

Back to Table of Contents 

4.8 Signal Processing:
Fourier Transforms and Related Topics

FFT and all FFT-based functions need additional buffer memory which they allocate and free internally. In order to allow this inefficiency to be avoided for multiple calls, all of these functions exist in an additional version, marked by the prefix VFb_, which takes a pointer to user-supplied buffer memory as an additional argument. The necessary size of this buffer memory is given for each function in its detailed description in FUNCREF.HTM.

Although they do not use Fourier transform methods, the functions VF_biquad (bi-quadratic audio filtering) and VF_smooth (crude form of frequency filtering which removes high-frequency noise) should be mentioned here.

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_polyfitOdd	fitting of one X-Y data set to a polynomial with odd terms only
VF_polyfitOddwW	the same for non-equal data-point weighting
VF_polyfitEven	fitting of one X-Y data set to a polynomial with even terms only
VF_polyfitEvenwW	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. subdivide the axes either linearly or logarithmically, according to the suffix of the AutoPlot function:

   V?_autoPlot (no suffix):	both X and Y axis linear.
   V?_autoPlot_xlg_ylin:	X axis logarithmic, Y axis linear.
   V?_autoPlot_xlg_ylg:	both X and Y axis logarithmic.
   V?_autoPlot_xlin_ylg:	X axis linear, Y axis logarithmic.

5. 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

Back to Table of Contents 

5. Error Handling

5.1 General Remarks

The production libraries of OptiVec treat all mathematical errors (Overflow, Singularity, Domain/Range, Loss-of-Accuracy) "silently" and continue program execution with a corrected result.
The Debug libraries, on the other hand, indicate the occurrence of errors by emitting a message, in addition to correcting the result. As described below, the function V_setFPErrorHandling can be called in order to control which errors will lead to a message. The function V_setErrorEventFile allows to choose if the messages are to be emitted into a log file, to a popup window, or into a console text window.
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 are limits to the ability of protection mechanisms to catch floating-point errors. Especially the extended-precision versions, but also the double-precision versions do not have much of a "safety margin". To be on the safe side, constant parameters should not exceed about 1.E32 for float, 1.E150 for double, and 1.E2000 for extended parameters.
>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.

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 <VSIstd.h>
#include <VSImath.h>
.....
main() /* or WinMain(), or OwlMain() */
{
  siVector SI1, SI2;
  SI1 = VSI_vector( 1000 ); SI2 = VSI_vector( 1000 );
  V_setIntErrorHandling( ierrNote );
  VSI_ramp( SI1, 1000, 0, 50 ); /* an overflow will occur here! */
  V_setIntErrorHandling( ierrIgnore );
  VSI_mulC( SI2, SI1, 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

Debug libraries only: As has been mentioned above, one may call V_setFPErrorHandling in order to select which error types lead to a message and which may lead to program execution being broken off. The available options are set by the predefined constants fperrXXX:

Option	Meaning
fperrIgnore	Treat all floating-point errors silently
fperrNoteDOMAIN	Notify in case of DOMAIN / ERANGE errors
fperrAbortDOMAIN	Notify and break off in case of DOMAIN / ERANGE errors
fperrNoteSING	Notify in case of Singularities (divisions by 0)
fperrAbortSING	Notify and break off in case of Singularities
fperrNoteOVERFLOW	Notify in case of Overflow
fperrAbortOVERFLOW	Notify and break off in case of Overflow
fperrNoteTLOSS	Notify in case of Total Loss of Precision (e.g., at sin(1.e30))
fperrAbortTLOSS	Notify and break off in case of Total Loss of Precision
fperrDefault	Default setting = fperrAbortDOMAIN + fperrNoteSING + fperrNoteOVERFLOW

 
When calling V_setFPErrorHandling, combine these constants by the + or better the OR operator. Note that this influences only the way errors are handled within OptiVec functions. It does not affect the way how the standard C/C++ or Pascal/Delphi functions handle errors.

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 / ERANGE 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. Range errors most often are the result of programming errors that should be fixed. The function VF_replaceNAN may be used to convert NAN's into any user-defined value.
  Note: the pseudo-numbers INF and NAN are not allowed as input for any functions of OptiVec except VF_replaceNAN, VF_limit, VF_minC, and VF_maxC, which may be called to clean up possible NAN's and INF's, respectively. Otherwise, INF and NAN are not tested for; their presence will normally result in an exception being raised.
• 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 result is never NAN, but always a "number", in most cases ±HUGE_VAL.
• OVERFLOW errors are the most abundant form of floating-point errors. They are always handled by setting the result to ±HUGE_VAL. Within many 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.
• 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 some compilers choose 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 modern compilers, PLOSS ("partial loss of precision") errors are never detected.

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 much 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 (ScreenAndFile = 0), or additionally into a message box (ScreenAndFile = 1) or, for console programmes, to the screen as well (ScreenAndFile = 2). By calling V_setErrorEventFile( "NULL", 0 ) (C/C++) or V_setErrorEventFile( 'nil', 0 ) (Pascal/Delphi), you can even completely switch any messages off (if you decide that is a wise thing to do).

Note that this redirection of error messages is valid only for errors occurring in OptiVec routines. It is possible, however, for a user program to use the OptiVec function V_printErrorMsg for its own error messages.

Certain configurations of the compilers supported by OptiVec do not allow the full set of options described above. For some, either output into a message box is missing or output to the console screen. In these cases, an error message is displayed and the output redirected to the available other option.

Back to Table of Contents

5.6 OptiVec Error Messages

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

Demo version only: Apparently, 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 copying the files from somewhere else, without using INSTALL.EXE. This is not possible, as INSTALL.EXE also starts the clock for the trial period. Install again, this time using INSTALL.EXE.

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

Demo 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 one of two mistakes: Either the parameter size has not been initialized (and contains some garbage with high bits set), or there are "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.
* 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 > 4 GB not possible (32-bit).

* Looks like you are trying to allocate a vector whose size exceeds the maximum of 4 GB in 32-bit. It is about time to switch to 64-bit!

(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. While this error might be harmless (e.g., you forgot that you already freed a vector and try to free it again), it might also be the result of rather serious problems. For example, a memory leak might have occurred and led to the vector variable being overwritten. Use the debug library in order to detect vector or matrix dimension mismatches, which are the principal cause of memory leaks, when you program with OptiVec.

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

• The choice of the OptiVec library must match your selection of memory model, processor, and environment. You are not going to have much fun with the library VCF4W.LIB (32-bit for C++ Builder) in 64-bit, and the libraries designed for Borland / Embarcadero C++ will not work with Visual C++ or any other compiler. Similarly, OVVCMTD.LIB, designed for multi-thread static debug in 32-bit Visual C++, will not work well in a multi-thread DLL debug 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...

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 the OWL (ObjectWindows Library) with old Borland compilers, 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, VUQstd, VUIstd	Standard operations for unsigned integer vectors
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, VUQmath, VUImath	Arithmetical and mathematical functions for unsigned integer vectors
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.
OVXMATH	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 OVXMATH)
FCSCTAB2, DCSCTAB2, ECSCTAB3, FCSCTAB3, DCSCTAB3, ECSCTAB3	cosecant tables (Pascal/Delphi only; for C/C++, they are in OVXMATH)
FTANTAB2, DTANTAB2, ETANTAB3, FTANTAB3, DTANTAB3, ETANTAB3	tangent tables (Pascal/Delphi only; for C/C++, they are in OVXMATH)
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