CMATH   

Site Index:

CMATH

This page describes the following products:
CMATH for Visual C++
CMATH for C++ Builder (formerly Borland C++)
CMATH for Delphi
CMATH for Lazarus / FPC
CMATH for GCC
CMATH for Linux GCC / CLang

Contents

1. Introduction

All functions may alternatively be called from classic C and Pascal/Delphi with type-specific function names (like cf_sin,   cd_exp,   pe_sqrt), or from C++ and Delphi with overloaded function names and operators (like sin,   exp,   sqrt,  operator +; operators only in C++). As far as possible, all functions have the same names in the Pascal/Delphi version as in the C/C++ version.

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++, C++ Builder (former Borland C++), and Delphi, CMATH is a high-quality replacement for the latter, which are all quite 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.

Back to CMATH Table of Contents   OptiVec home 

1.1 C/C++ Specifics

Here is a detailed description of how to use CMATH in your projects:

1. In C++ modules, declare
   #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, the word 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.
    

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 (Embarcadero/Borland C++ version) or double (MSVC version).
    
4. The constituent parts of the C++ classes are declared as public. 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.
    
5. 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 CMATH Table of Contents   OptiVec home 

1.2 Delphi Specifics

CMATH for 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/Delphi. Therefore, this name is derived from the C/C++ analogue of Single, which is float.

The CMATH-Delphi 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 C supports complex numbers (defined as structs) as return values, whereas Pascal and early Delphi versions originally did not allow records to be returned by a function (this is allowed only in Delphi). Therefore, they are passed 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 CMATH Table of Contents   OptiVec home 

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, 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 );

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:

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.

Back to CMATH Table of Contents   OptiVec home 

2.3 Basic Complex Operations

Back to CMATH Table of Contents   OptiVec home 

2.4 Arithmetic Operations

Additionally, all arithmetic operations of complex numbers are implemented as functions which actually provide the most efficient implementation:
 

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

Back to CMATH Table of Contents   OptiVec home 

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 CMATH Table of Contents   OptiVec home 

3. Error Handling

3.1 General Error Handling of Complex Functions

In contrast to the arithmetic operations, all mathematical functions 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.

3.1.1 C/C++ Specifics

Back to CMATH Table of Contents   OptiVec home 

3.1.2 Pascal/Delphi Specifics

Back to CMATH Table of Contents   OptiVec home 

3.2 Writing Error Messages into a File

Back to CMATH Table of Contents   OptiVec home 

4. Syntax Reference

Back to CMATH Table of Contents   OptiVec home 

4.1 Plain-C, Pascal/Delphi Functions

Back to CMATH Table of Contents   OptiVec home 

4.2 Overloaded C++/Delphi Functions

Back to CMATH Table of Contents   OptiVec home 

Copyright © 1996-2020 OptiCode - Dr. Martin Sander Software Development