CMATH   

Site Index:

CMATH

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.

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, 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 (Borland C++ version) or double (MSVC version).
    
4. 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.
    
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 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 C supports complex numbers (defined as structs) as return values, whereas Pascal 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 available only in Delphi (not in the Turbo Pascal version). They 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 );

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 lead to an error message; 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 caught and treated via _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 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.

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

Since it is only the language C++, 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_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 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 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.

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

fComplex cf_tanh( fComplex __z );
procedure cf_tanh( var zy:fComplex; zx:fComplex );

Back to CMATH Table of Contents   OptiVec home 

4.2 Overloaded C++/Delphi Functions

fComplex tanh( fComplex _z );
function tanh( zx:fComplex ): fComplex;

Back to CMATH Table of Contents   OptiVec home 

Copyright © 1998-2012 OptiCode - Dr. Martin Sander Software Development