CMATH   Version 8 for C/C++ and for Pascal (Delphi, Lazarus)
OptiCode Dr. Martin Sander Software Development Brahmsstr. 6 D-32756 Detmold Germany http://www.optivec.com e-mail: optivec@gmx.de

CMATH is available both separately and as a part of OptiVec. If you ordered or downloaded CMATH alone, please disregard all references to OptiVec in this documentation.
If you got CMATH as a part of OptiVec, you may wish to refer to HANDBOOK.HTM for a description of the basic principles of the OptiVec libraries and an overview over VectorLib, the first part of OptiVec. The second part, MatrixLib is described in MATRIX.HTM.
Chapter 1.2 of this file contains the licence terms for the Shareware version, Chapter 1.3 for the Registered version.
 
OptiCode™ and OptiVec™ are trademarks of Dr. Martin Sander Software Dev. Other brand and product names mentioned in this handbook for identification purposes are trademarks or registered trademarks of their respective holders.
 

Translations:	Sie finden die deutsche Beschreibung separat unter CMDOCD.ZIP.
	Lithuanian translation provided by Giedrius Sadauskas
	Translation into Serbo-Croatian by Jovana Milutinovich from Webhostinggeeks.com

Contents

1. Introduction

1.1 What is CMATH ?

Superior speed, accuracy and safety are achieved through the implementation in Assembly language (as opposed to the compiled or inline code of available complex C++ class libraries). Only for the most simple tasks, alternative inline C++ functions are used in the C++ version.

As far as the scope of CMATH overlaps with the complex class implementations of Visual C++, Borland C++, and Delphi / Lazarus, CMATH is a high-quality replacement for the latter, which are all awfully inefficient and inaccurate.

In contrast to the written-down-and-compiled textbook formulas of most other available complex libraries (including those coming with Visual C++ and the Borland compilers), the implementation of CMATH was guided by the following rules:

1. Without any compromise, top priority is always given to the mathematically correct result, with the accuracy demanded for the respective data type. Especially for complex functions, this necessitates a very thorough treatment of many different situations. To this end, the various cases have to be distinguished with pedantic care. (Textbook formulas do not need to treat these situations separately, as they theoretically assume infinite accuracy of intermediate results; an actual implementation, however, has to work with the limited accuracy given by real-life processors.)
2. Mathematical functions must be "safe" under all circumstances. They may for no reason simply crash, but have to perform a decent error treatment. This is true even - and perhaps especially - for seemingly nonsense arguments, with the single exception of the non-numbers INF and NAN, which occur themselves only as a result of serious errors in other functions.
3. By all possible means, greatest execution speed must be attained. (After all, you did not buy your fast computer for nothing!)
4. The program code has to be as compact as possible. However, in case of conflicts, faster execution speed is always given priority over smaller code size.

This documentation describes the CMATH implementations for

• the Embarcadero / Borland / CodeGear series of C/C++ compilers (all versions of RAD Studio, Borland C++ Builder and Borland C++, back even to BC 5.0) for Win64 and Win32 (native Win64 / Win32 only; no .NET applications!).
• Microsoft Visual C++ (all version of Microsoft Visual Studio and MSVC from the present down to VS 2005) for 32-bit and 64-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, all versions from Delphi 2009 on (RAD Studio, BDS, Stand-alone Delphi) on 32-bit and 64-bit Windows
• Lazarus / FreePascal, exclusively 64-bit Windows platform.

1. 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 CMATHFS.LIB + CMATHF4W.LIB. For details, see chapter 1.4.
    
2. Microsoft Visual C++:
   The Shareware version offers the libraries for "multi-thread debug (static RTL)", and "multi-thread DLL debug". The full (registered) version for Microsoft Visual C++ also contains the corresponding release libraries. There is no actual debug information enclosed in the OptiVec "debug" libraries, but they have to be used with the debug libraries of Visual C++.
   The 32-bit Shareware version runs on any processor from Pentium or Athlon on.
   The 64-bit Shareware version requires at least a Core2xxx or AMD x64 processor.
3. GCC and LLVM CLang:
   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.
    
4. Delphi:
   Each Delphi release requires its own OptiVec library version.
    
5. Lazarus:
   All CMATH 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 CMATH function names would not be found in the included *.o files.
   The Shareware version requires, at least, a Pentium-class or Athlon computer. The Registered version offers an additional library optimized for current processors.

Back to Table of Contents

1.1.1 C/C++ Specifics

Here is a detailed description of how to switch from the complex classes of Borland C++ to the new implementation given by CMATH:

1. In C++ modules, replace the statement
   #include <complex.h>
   by the statement
   #include <newcplx.h>
   Then, the following six complex classes are defined:
   class complex<float>, class complex<double>, class complex<long double>, class polar<float>, class polar<double>, and class polar<long double>.

   The data types fComplex, dComplex, eComplex, fPolar, dPolar, and ePolar are defined as synonyms for these classes.
   In order to avoid the letter "L" (which is already over-used by long and unsigned long, extended is used as a synonym for long double in the Borland C++ version of CMATH. In the MSVC version, it is a synonym for double, as MSVC does not support 80-bit IEEE reals. Consequently, the complex data types of extended precision are named eComplex and ePolar. Thereby, the way is held open for a future inclusion of whole-number complex types into CMATH. Then, liComplex and ulComplex shall denote the complex types consisting of long int and unsigned long parts, respectively.

    
2. If you prefer to have the "classic" class complex of older releases of Borland C++, you have to declare
   #define CMATH_CLASSIC_COMPLEX
   before (!) including <newcplx.h>.
   In this case, only the class complex will be defined and gets the synonym dComplex. Here you will have no access to the complex-number functions of float and of extended precision, and all functions in polar coordinates are unavailable as well.
    
3. For plain-C modules, you cannot include <newcplx.h>. Rather, please declare
   #include <cmath.h>
   If you are using only one level of floating-point precision, you may wish to include only one of the type-specific include-files: <cfmath.h>, <cdmath.h>, or <cemath.h>, respectively.
   The plain-C implementation of CMATH is based upon the following definitions of the complex data types:
   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;
   As described above, the data type extended is used as a synonym for long double (Borland C++ version) or double (MSVC version).
    
4. Replace calls to the complex member function polar by calls to magargtoc.
    
5. The constituent parts of the C++ classes are declared as public (in contrast to Borland C++ !). They are named "Re" and "Im" in the cartesian classes, and "Mag" and "Arg" in the polar classes. This allows to access them as z.Re, z.Im, p.Mag, or p.Arg in C++ modules as well as in plain-C modules.
    
6. For time-critical applications, we recommend to use the C rather than the C++ version of CMATH, as C/C++ compilers handle structs much more efficiently than classes. To use the C version with your C++ modules, please note the following points:
   • include <cmath.h> instead of <newcplx.h>
   • for initialization, assign the real/imaginary or Mag/Arg parts directly (e.g., z.Re = 3; z.Im = 5; ) or use the functions fcplx, dcplx, ecplx, fpolr, dpolr, epolr. The constructors complex(), fComplex(), polar(), fPolar(), etc. are not available.
   • if you do a C++ compile on modules with <cmath.h> included, you have the choice between calling CMATH functions by their type-specific names (like cf_sin,   cd_exp), or by their overloaded C++ names (e.g., sin,   exp). On some occasions, you might be forced to use the type-specific names in order to resolve ambiguities.

Back to Table of Contents

1.1.2 Pascal/Delphi Specifics

CMATH for Pascal/Delphi defines six complex data types:
type fComplex = record Re, Im: Single; 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;

The reason why the single-precision type gets the name fComplex instead of sComplex is that the letter "s" is already over-used by ShortInt and SmallInt in Pascal. Therefore, this name is derived from the C/C++ analogue of Single, which is float.

The CMATH-Pascal data types are binary compatible with those of the C/C++ versions.

The type-specific function names are the same as in the plain-C version. The syntax, however, is somewhat different, as complex numbers as return values could be implemented most efficiently by passed them as var arguments to the complex functions, e.g.
procedure cf_sin( var zy:fComplex; zx:fComplex );

The overloaded function names are the same as in the C++ version. Here, the results are treated as true return values, e.g.
function sin( zx:fComplex ): fComplex;

Back to Table of Contents

1.2 Licence Terms for the Shareware 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 Shareware 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. Special conditions apply for the 32-bit P4 and the 64-bit P8 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.
4. 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).
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 CMATH 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

For any other questions related to ordering CMATH, please contact us at: 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, of fitness for a particular purpose, or of noninfringement 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

If you got CMATH as a part of OptiVec, you should read chapter 1.4 of HANDBOOK.HTM instead of the remainder of the present paragraph. If you have already read that, continue with chapter 2, or go back to the Table of Contents.

In order to use CMATH, you need an already installed copy of your C/C++, Delphi, or Pascal compiler. Install CMATH by executing INSTALL.EXE. Normally, CMATH will be installed into a directory named "CMATH". This directory holds the documentation. You will need to include the CMATH lib and include (C/C++) or units (Delphi) subdirectories into the search path.
Jump to the description for your specific version:

	CMATH for C++ Builder (Embarcadero / Borland C++)
	CMATH for Visual C++
	CMATH for GCC
	CMATH for LLVM CLang
	CMATH for Delphi
	CMATH for Lazarus / FreePascal

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

You have to include not only one, but two CMATH libraries: First the CMATH base library:
 

Platform	Compiler	static runtime library	runtime library as DLL
Win64	bcc64, from RAD Studio 12 (2023) on	cmbcbase64.a	cmbcbase64.a
	bcc64, all versions until RAD Studio 11.x	cmbcx64.a	cmbcx64.a
Win32	bcc32 (classic), RAD Studio 12+	cmbcbase32s.lib	cmbcbase32d.lib
	bcc32 (classic), all versions until RAD Studio 11.x	cmathfs.lib	cmathfd.lib
	bcc32c (CLang-enhanced), RAD Studio 12+	cmbcbase32cs.lib	cmbcbase32cd.lib
	bcc32c (CLang-enhanced), RADS 10.x, 11	cmbc10_11base32cs.lib	cmbc10_11base32cd.lib

Second, select the required processor-specific library from the following table and add it to your project.
 

Platform	Compiler	Processor back-compatibility	CMATH Library
Win64	bcc64	min. Core2xx, AMD x64)	CMBC64_8.a
Win32	bcc32 (classic)	current processors (min. Core2xx, AMD x64)	CMATHF8W.LIB
		486DX/Pentium	CMATHF4W.LIB
	bcc32c (CLang) from C++ Builder 10.1 Berlin on	current processors (min. Core2xx, AMD x64)	cmbc32c_8.lib
		486DX/Pentium	cmbc32c_4.lib
	bcc32c (CLang) up until C++ Builder 10 Seattle	current processors (min. Core2xx, AMD x64)	CMATHF8W.LIB
		486DX/Pentium	CMATHF4W.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 CMATH functions in C/C++

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

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

Processor	32-bit CMATH library	64-bit CMATH library
P8: latest processors (Core2xxx, i3, i5, i7, AMDx64)	CMVC8.LIB	CMVC64_8.LIB
P4: full FPU accuracy (at least 486DX/Pentium)	CMVC4.LIB	----

 
In order to allow CMATH to be used in applications both with and without MFC, it calls the Windows API only directly, not via MFC. However, if you use MFC (either as a static library or as a DLL), Visual C++ does not automatically link the import library, user32.lib. You have to explicitly do this yourself: The line, Project / Settings / Linker / Object and Library Modules must contain user32.lib. Otherwise you would get the linker error "error LNK2001: Unresolved external symbol __imp__MessageBoxA@??".
 

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

1.4.3 CMATH for GCC (GNU Compiler Collection)

You have to include two CMATH libraries. The first one ("base library") contains the interface between CMATH 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 CMATH 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 CMATH library according to the following table:
 

Processor	32-bit CMATH library	64-bit CMATH library
P8: latest processors (Core2xxx, i3, i5, i7, AMDx64)	cmgc32_8.lib	cmgc64_8.lib
P4: full FPU accuracy (at least 486DX/Pentium)	cmgc32_4.lib	----

 

One very important point to observe when working with GCC is that the linker resolves dependencies from "left to right". As the processor-specific library calls functions from the base library, the processor-specific library needs to be included first.

GCC is the only of the "big" compilers to support 80-bit real numbers (long double or extended) in 64-bit (all other compilers implicitly demote long double / extended do double). This is a very valuable feature, as the extra accuracy and range can make life much simpler on many occasions. CMATH supports eComplex, i.e., complex numbers in extended precision, both in 32-bit and in 64-bit.

A Linux version of CMATH for GCC is being prepared and will be included, when it becomes available.

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

1.4.4 CMATH for LLVM CLang

You have to include two CMATH libraries. The first one ("base library") contains the interface between CMATH 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 CMATH 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 CMATH library	64-bit CMATH library
P8: latest processors (Core2xxx, i3, i5, i7, AMDx64)	cmcl32_8.lib	cmcl64_8.lib
P4: full FPU accuracy (at least 486DX/Pentium)	cmcl32_4.lib	----

A Linux version of CMATH for LLVM CLang is being prepared and will be included, when it becomes available.

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

1.4.5 CMATH for Delphi

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

1.4.6 OptiVec for Lazarus / FreePascal

1.5 Declaration of CMATH functions

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

1.5.2 Declare the use of CMATH functions in Pascal / Delphi

1.6 Sample programs

• Microsoft Visual C++:
  Open the project map CDEMO_vs20??.sln or CDEMO64_vs20??.sln for you VS version.
• Embarcadero / Borland C++:
  12, 11.x, 10.x, XE3 or higher: Open the project group CDEMO.groupproj (both 64-bit and classic Borland 32-bit compiler) or CDemo_BCC32C.groupproj (Clang-enhanced compiler BCC32C; 32-bit only)
  Alternatively (for older versions: always) open the individual projects:
  CDEMO.cbproj and MANDEL.cbproj are projects for RAD Studio 2009, 2010, XE
  CDEMO.bdsproj and MANDEL.bdsproj are for BDS 2006 and 2007
  CDEMOB6.BPR and MANDELB6.BPR are for BC++ Builder 6+.
• GCC:
  The make file "makefile." contains the two targets CDemo and Mandel. 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 the modified-Mandelbrodt demo program "Mandel", present for the other compilers, relies on graphics output, it is not available until this CLang glitch will be fixed.
• Delphi:
  Open CDEMO.dproj or MANDEL.dproj
• Lazarus:
  Check CDEMO.lpi and MANDEL.lpi.

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

Back to Table of Contents

2. Overview over the Functions of CMATH

In C++ and Delphi, synonyms are defined for all these functions. The synonyms do not have a prefix, since the data type information is implicitly handled by the compiler. The overloaded function names are mostly identical to those found in the complex class libraries (if the respective function exists there). Note, however, that the member function polar had to be replaced by magargtoc, as the name "polar" is now reserved for the polar classes.

C++ only: If you wish to use the C function names in your C++ modules, be sure to include <cmath.h> instead of <newcplx.h>.

2.1. Initialization of Complex Numbers

In the following, we denote the complex classes by by their short names, fComplex, fPolar, etc. In C++, you can always use the template nomenclature instead, writing "complex<float>" wherever "fComplex" is written here, and so on for all other complex types and classes.

Complex numbers are initialized by separately assigning a value to the imaginary and real parts or to the Mag and Arg parts, e.g.:
z.Re  = 3.0; z.Im  = 5.7;
p.Mag = 8.8; p.Arg = 3.14;
(Of course, for Pascal/Delphi, the assignment operator is written ":=").
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.

2.2. Data-Type Interconversions

Interconversions between the various complex types are performed via the functions:

cftocd,   cdtocf,   cftoce,   cetocf,   cdtoce,   cetocd	up- or down-conversion of accuracy within the cartesian-complex types
pftopd,   pdtopf,   pftope,   petopf,   pdtope,   petopd	up- or down-conversion of accuracy within the polar-complex types
cftopf,   cftopd,   cftope, cdtopf,   cdtopd,   cdtope, cetopf,   cetopd,   cetope	conversion from cartesian into polar complex
pftocf,   pftocd,   pftoce, pdtocf,   pdtocd,   pdtoce, petocf,   petocd,   petoce	conversion from polar into cartesian complex

 
OVERFLOW errors in the course of down-conversions are silently cured: program execution is continued with the largest value possible.

C++ only:

For C++ modules, there are several overloaded constructors as an alternative to the above functions: basic forms:    fComplex fComplex( float RePart, float ImPart=0 );    fComplex fComplex( dComplex );    fComplex fComplex( eComplex );    fPolar fPolar( float MagPart, float ArgPart=0 );    fPolar fPolar( dPolar );    fPolar fPolar( ePolar ); interconversion cartesian <--> polar:    fComplex fComplex( fPolar );    fComplex fComplex( dPolar );    fComplex fComplex( ePolar );    fPolar fPolar( fComplex );    fPolar fPolar( dComplex );    fPolar fPolar( eComplex ); Similarly to the constructors fComplex() and fPolar(), also dComplex(), dPolar(), eComplex, and ePolar() exist in overloaded versions performing the same tasks for the classes dComplex, dPolar, eComplex, and ePolar, respectively. As described above for the C/Pascal/Delphi versions, OVERFLOW errors in the course of down-conversions are silently cured, without calling _matherr.

 
A special constructor for polar numbers is
fPolar pf_principal( fPolar __p );
and, for C++ only, its overloaded form for two separate real input numbers
fPolar principal( float Mag, float Arg );
These functions reduce the input Arg to the range -p < Arg <= +p. You might recall that each complex number has an infinite number of representations in polar coordinates, with the angles differing by an integer multiple of 2 p. The representation with -p < Arg <= +p is called the principal value.
Please note that, along with the polar square-root function, pf_sqrt, these are the only polar functions reducing the output to the principal value. All others accept and return arguments whose angles may fall outside this range.

The conversion between cartesian and polar format involves transcedental functions and is, therefore, quite time-consuming. It is true that multiplications are faster in polar coordinates, whereas additions are much faster in Cartesian. The difference, however, is so much smaller than the cost of switching back and forth between the different representations, that we recommend you stay in general with the cartesian format. Only in the following cases, the conversion really makes sense:

1. You have only multiplications and related math functions (like square,  sqrt,  ipow). Then, you should start out with polar coordinates.
2. You have to call the complex exponential function. In this case, cf_exptop brings you into polar coordinates in a very natural manner.
3. You are in polar coordinates and have to calculate the logarithm. In this case, pf_logtoc (or similarly pf_log2toc,   pf_log10toc) brings you "down" to the cartesian representation.

Zurück zum Inhaltsverzeichnis

2.3 Basic Complex Operations

Back to Table of Contents

2.4 Arithmetic Operations

Since it is only C++ and Delphi, but neither plain-C nor Pascal, which allows overloaded arithmetic operators, all arithmetic operations of complex numbers are implemented additionally as functions which may be called from C/Pascal/Delphi as well as C++ modules:
 

Cartesian	Polar
cf_add	N.A.	addition of two complex numbers
cf_addRe	N.A.	addition of a complex number and a real number
cf_sub	N.A.	subtraction of two complex numbers (first operand minus the second operand)
cf_subRe	N.A.	subtraction of a real number from a complex number
cf_subrRe	N.A.	subtraction of a complex number from a real number
cf_mul	pf_mul	multiplication of two complex numbers
cf_mulRe	pf_mulRe	multiplication of a complex number and a real number
cf_mulconj	pf_mulconj	multiplication of one complex number with the complex conjugate of another
cf_div	pf_div	division of two complex numbers (first operand divided by the second operand)
cf_divRe	pf_divRe	division of a complex number by a real number
cf_divrRe	pf_divrRe	division of a real number by a complex number

(similarly the double- and extended-precision versions) 

The assignment operator "=" or ":=" is the only operator defined also in plain-C and Pascal/Delphi for complex numbers.

Back to Table of Contents

2.5 Mathematical Functions

As noted above, the exponential and logarithm functions provide a natural transition between cartesian and polar coordinates. While there are exp and log functions for fComplex as argument and as return value, cf_exptop takes an fComplex argument and returns fPolar. In the opposite direction, pf_logtoc takes an fPolar argument and returns fComplex.

Back to Table of Contents

3. Error Handling

3.1 General Error Handling of Complex Functions

In contrast to the arithmetic operations, all mathematical functions and all data-type interconversions perform a tight error checking. All error messages eventually generated use the C/Pascal name (rather than the overloaded C++/Delphi name) of the failing function.

If you got CMATH as a part of OptiVec, you should read chapter 5 of HANDBOOK.HTM rather than the present chapter.

Overflow, singularity, and loss-of-precision errors are treated by setting the result to the default value appropriate for each function. DOMAIN / ERANGE errors lead to the result NAN (not-a-number).

Debug libraries only: One may call V_setFPErrorHandling( int fpHandlingMode ); 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)
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.
The repeated occurrence of the same type of error within one and the same function will lead to only one message being generated. Subsequent errors will be treated silently.

Back to Table of Contents

3.2 Advanced Error Handling: Writing Messages into a File

You might wish to circumvent this. To this end, OptiVec and CMATH provide the function V_setErrorEventFile. This function needs as arguments the desired name of your event file and a switch named ScreenAndFile which decides if you wish to have error messages printed simultaneously into the file and onto the screen (ScreenAndFile = TRUE (non-zero)) or exclusively into the file (ScreenAndFile = FALSE (0)).

Example:
V_setErrorEventFile( "MyLogFil.TXT", 0 ); /* C/C++ */
V_setErrorEventFile( 'MyLogFil.TXT', FALSE ); (* Pascal/Delphi *)
Here, you will get all subsequent error messages only into your log file, MyLogFil.TXT and no messages on the screen. The default, i.e., printing error messages to the screen, is restored by V_closeErrorEventFile. (That function does not take any arguments and does not return anything.)

Note that this redirection of error messages is valid only for errors occurring in OptiVec (CMATH) routines. It is possible, however, for a user program to use V_printErrorMsg( const char *MyMessage ) for its own error messages.

Certain configurations of the compilers supported by CMATH 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.

Zurück zum Inhaltsverzeichnis

4. Syntax Reference

Zurück zum Inhaltsverzeichnis

4.1 Plain-C, Pascal/Delphi Functions

Back to Table of Contents

4.2 Overloaded C++/Delphi Functions

Back to Table of Contents

E N D