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.
CMATH is a comprehensive library for complex-number arithmetics and mathematics, both in cartesian and in polar coordinates. All functions may alternatively be called from classic C and Pascal with type-specific function names (like cf_sin, cd_exp, pe_sqrt), or from C++ and Pascal/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++, 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:
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.)
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.
By all possible means, greatest execution speed must be attained. (After all, you did not buy your fast computer for nothing!)
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.
Please note that only the "outside appearance" and thus the documentation is the same for these different compilers. The libraries themselves are compiler-specific; each library can be used only with one compiler and, in the case of C/C++, with one memory model or one target:
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.
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.
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.
Delphi: Each Delphi release requires its own OptiVec library version.
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.
The complex C++ classes and the C structs fComplex etc. are binary compatible with each other. This point may become important for large projects with mixed C and C++ modules. Existing C++ code which uses the complex class library of Borland C++, contained in <complex.h>, can be left unchanged, because the CMATH functions and data types are also binary compatible with those of <complex.h>. The single exception is the member function polar, which had to be replaced by magargtoc, as the word "polar" now denotes the complex classes in polar coordinates.
Here is a detailed description of how to switch from the complex classes of Borland C++ to the new implementation given by CMATH:
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.
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.
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).
Replace calls to the complex member function polar by calls to magargtoc.
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.
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.
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;
In case you got CMATH as a part of OptiVec, the CMATH licence is included in the OptiVec licence. Otherwise, the following licence terms apply to the Shareware version of CMATH.
For the licence terms of the Registered version, please see paragraph 1.3.
This is the Shareware version of CMATH ("SOFTWARE").
It may be used under the following licence terms:
You may test the SOFTWARE free of charge for a period of up to 90 days on one computer.
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.
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.
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).
This SOFTWARE is provided on an "as is" basis. Any explicit or implicit warranties for the SOFTWARE are excluded.
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.
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.
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.
You can either get a license for the CMATH version designed for one specific compiler ("CMATH for xxx"), or you can acquire a CMATH Master License, covering all supported compilers.
In order to make this product affordable also for those who will not themselves make money using it, we offer an educational edition at a strongly reduced rate, in addition to the full commercial edition. The contents of these two editions is identical. The only difference lies in the restrictions of use: The educational edition may not be used for commercial / business / government purposes, but is restricted to private and educational use.
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
OptiVec for single compilers: C++ Builder, Visual C++, GCC (Win), LLVM CLang (Win), Delphi, Lazarus / FreePascal, or Linux (GCC / LLVM CLang)
Prices incl. 19% German VAT
Prices net
Commercial Edition
Single license
5 units
10 units
EUR 199
EUR 595 (119.00 per unit)
EUR 995 ( 99.50 per unit)
EUR 167.23
EUR 500.00 (100.00 per unit)
EUR 836.13 ( 83.61 per unit)
Educational Edition
Single license
5 units
10 units
EUR 99
EUR 269 ( 53.80 per unit)
EUR 499 ( 49.90 per unit)
EUR 83,19
EUR 226.05 ( 45.21 per unit)
EUR 419.33 ( 41.93 per unit)
OptiVec Master License for all supported compilers
Prices incl. 19% German VAT
Prices net
Commercial Edition
Single license
5 units
10 units
EUR 299
EUR 899 (179.80 per unit)
EUR 1499 ( 149.90 per unit)
EUR 251.26
EUR 755.46 (151.09 per unit)
EUR 1259.66 (125.97 per unit)
Educational Edition
Single license
5 units
10 units
EUR 149
EUR 445 (89.00 per unit)
EUR 745 (74.50 per unit)
EUR 125.21
EUR 373.95 (74.79 per unit)
EUR 626.05 (62.61 per unit)
CMATH for single compilers: C++ Builder, Visual C++, GCC (Win), LLVM CLang (Win), Delphi, Lazarus / FreePascal, or Linux (GCC / LLVM CLang)
Prices incl. 19% German VAT
Prices net
Commercial Edition
Single license
5 units
10 units
EUR 59
EUR 175 (35.00 per unit)
EUR 295 (29.50 per unit)
EUR 49.58
EUR 147.06 (29.41 per unit)
EUR 247.90 (24.79 per unit)
Educational Edition
Single license
5 units
10 units
EUR 29
EUR 85 (17.00 per unit)
EUR 145 (14.50 per unit)
EUR 24.37
EUR 71.43 (14.29 per unit)
EUR 121.85 (12.19 per unit)
CMATH master license for all supported compilers
Prices incl. 19% German VAT
Prices net
Commercial Edition
Single license
5 units
10 units
EUR 89
EUR 265 (53.00 per unit)
EUR 445 (44.50 per unit)
EUR 74.79
EUR 222.69 (44.54 per unit)
EUR 373.95 (37.40 per unit)
Educational Edition
Single license
5 units
10 units
EUR 49
EUR 145 (29.00 per unit)
EUR 245 (24.50 per unit)
EUR 41.18
EUR 121.85 (24.37 per unit)
EUR 205.88 (20.59 per unit)
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.
In case you got CMATH as a part of OptiVec, the CMATH licence is included in the OptiVec licence. Otherwise, these are the license terms valid for you, if you got this file with the registered version of CMATH:
This is a single copy license for CMATH ("SOFTWARE"), granted by OptiCode - Dr. Martin Sander Software Development ("OptiCode").
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:
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.
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.
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.
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.
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.
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.
Limited Warranty for the Registered version
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.
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.
Any magnetic/optic or printed media from this package proving defective in materials or workmanship will be replaced on an exchange basis.
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.
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.
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.
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:
1.4.1 CMATH for C++ Builder (Embarcadero / Borland C++)
Assuming your CMATH directory is C:\CMATH, add
C:\CMATH\LIB to the library search path and
C:\CMATH\INCLUDE to the include-file search path of the IDE (and of the configuration file BCC32.CFG in case you are using the command-line compilers).
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.
1.4.2 CMATH for Visual C++ (Microsoft Visual Studio)
Assuming your CMATH directory is C:\CMATH, add
C:\CMATH\LIB to the library search path and
C:\CMATH\INCLUDE to the include-file search path.
You have to include two CMATH libraries. The first one ("base library") contains the interface between CMATH and the VC++ runtime library; it has to be matched with the specific version of the VC++ runtime library you chose for your project. 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 project configuration and runtime library. The latter is set at Project / (Configuration) Settings / C/C++ / Code Generation / Runtime Library. Under Project / (Configuration) Settings / Linker / Input, add the matching CMATH library to your project, according to the following table.
Platform
Visual Studio Version
Runtime: Debug DLL
Debug Static
Release DLL
Release Static
Win64
VS 2022
CMVC17x64MDD.LIB
CMVCx64MTD.LIB
CMVC17x64MDR.LIB
CMVCx64MTR.LIB
Win64
VS 2019
CMVC16x64MDD.LIB
CMVCx64MTD.LIB
CMVC16x64MDR.LIB
CMVCx64MTR.LIB
VS 2017
CMVC15x64MDD.LIB
CMVCx64MTD.LIB
CMVC15x64MDR.LIB
CMVCx64MTR.LIB
VS 2015
CMVC14x64MDD.LIB
CMVCx64MTD.LIB
CMVC14x64MDR.LIB
CMVCx64MTR.LIB
VS 2013
CMVC12x64MDD.LIB
CMVC8_12x64MTD.LIB
CMVC12x64MDR.LIB
CMVC8_12x64MTR.LIB
VS 2012
CMVC11x64MDD.LIB
CMVC8_12x64MTD.LIB
CMVC11x64MDR.LIB
CMVC8_12x64MTR.LIB
VS 2010
CMVC8x64MDR.LIB*
CMVC8_12x64MTD.LIB
CMVC8x64MDR.LIB*
CMVC8_12x64MTR.LIB
VS 2008
CMVC8x64MDR.LIB*
CMVC8_12x64MTD.LIB
CMVC8x64MDR.LIB*
CMVC8_12x64MTR.LIB
VS 2005
CMVC8x64MDD.LIB
CMVC8_12x64MTD.LIB
CMVC8x64MDR.LIB
CMVC8_12x64MTR.LIB
Win32
VS 2022
CMVC17MDD.LIB
CMVCMTD.LIB
CMVC17MDR.LIB
CMVCMTR.LIB
VS 2019
CMVC16MDD.LIB
CMVCMTD.LIB
CMVC16MDR.LIB
CMVCMTR.LIB
VS 2017
CMVC15MDD.LIB
CMVCMTD.LIB
CMVC15MDR.LIB
CMVCMTR.LIB
VS 2015
CMVC14MDD.LIB
CMVCMTD.LIB
CMVC14MDR.LIB
CMVCMTR.LIB
VS 2013
CMVC12MDD.LIB
CMVC8_12MTD.LIB
CMVC12MDR.LIB
CMVC8_12MTR.LIB
VS 2012
CMVC11MDD.LIB
CMVC8_12MTD.LIB
CMVC11MDR.LIB
CMVC8_12MTR.LIB
VS 2010
CMVC10MDD.LIB
CMVC8_12MTD.LIB
CMVC10MDR.LIB
CMVC8_12MTR.LIB
VS 2008
CMVC9MDD.LIB
CMVC8_12MTD.LIB
CMVC9MDR.LIB
CMVC8_12MTR.LIB
VS 2005
CMVC8MDD.LIB
CMVC8_12MTD.LIB
CMVC8MDR.LIB
CMVC8_12MTR.LIB
*For the outdated VS versions 2008 and 2010, the 64-bit base-libraries for dynamic runtime are not available. As a work-around, you may use the VS2005 library instead. In this case, however, you may have to install additional redistributable DLL's. You find these redistributables at www.microsoft.com/download. Enter "vcredist_x86" or "vcredist_x64" into the search field to get a list of available redistributables. Choose the ones for Visual Studio 2005.
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 CMath base libraries CMVC??MDD.lib and CMVC??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 CMath.
After that, please add the second, processor-specific CMATH library according to the following table:
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@??".
Assuming your CMATH directory is C:\CMATH, you need to compile with the option -I C:\CMATH\Include.
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:
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.
Assuming your CMATH directory is C:\CMATH, you need to compile with the option -I C:\CMATH\Include.
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:
Shareware version: The units (.DCU files) are in the directory CMATH\LIB4 (32-bit) or CMATH\Win64\LIB8 (64-bit). Registered version: The units (.DCU files) for current processors are in CMATH\LIB8 (32-bit) and CMATH\Win64\LIB8 (64-bit) / CMATH\Win64\LIB8D (64-bit Debug), those for 32-bit museum hardware (down to Pentium and 486DX) are in CMATH\LIB4 and in CMATH\LIB4D (Debug).
You need to set the units search path accordingly.
The units (.PPU files) and object files (*.o) are in the directory CMATH\LIB8. You need to enter this information into the "Other Units" search path.
1.5 Declaration of CMATH functions
1.5.1 Declare the use of CMATH functions in C/C++
Declare the use of CMATH functions in your program by the directive
#include <newcplx.h> (only C++, not plain-C) or
#inlucde <cmath.h> (both plain-C and C++), as described above.
If you are writing MFC or Borland C++ ObjectWindows applications, the CMATH header files should be included after the MFC or OWL header files.
1.5.2 Declare the use of CMATH functions in Pascal / Delphi
Declare the use of CMATH units as usual with the "uses CMATH" statement.
1.6 Sample programs
Have a look into the sample programs by opening the project appropriate for your compiler:
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.
In the following, it is often only the fComplex or fPolar version of a function that is explicitly mentioned. The versions for dComplex / dPolar, and eComplex / ePolar are always exactly analogous.
All functions for the languages C and Pascal/Delphi have a prefix denoting the data type on which the function works:
"cf_" or "pf_" stands for single precision (arguments and return values of the data types fComplex, fPolar, sometimes together with float),
"cd_" or "pd_" stands for double precision (arguments and return values of the data types dComplex, dPolar, sometimes together with double), whereas
"ce_" and "pe_" denote extended-precision functions.
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 );
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:
You have only multiplications and related math functions (like square, sqrt, ipow). Then, you should start out with polar coordinates.
You have to call the complex exponential function. In this case, cf_exptop brings you into polar coordinates in a very natural manner.
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.
Arithmetic operators are available for all complex classes / data types. They exist also for "mixed" arguments, where one argument is complex, the other real and where the arguments are of different floating-point accuracies.
Instead of the operators defined for the more recent Delphi versions, you can use the following functions:
add sub mul divide
They work for two complex arguments or for one complex and one real argument.
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:
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.
The error handling of complex functions follows the rules employed generally also for real-number functions and operations. For all arithmetic operations, the design of the algorithms eliminates the danger of failure due to irregular intermediate results. Overflowing or otherwise irregular final results, however, will lead to a hardware interrupt being generated and, as a consequence, to a program abort.
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
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.
3.2 Advanced Error Handling: Writing Messages into a File
Quite generally, the libraries shipped with compilers do not offer the programmer much control over the way error messages are printed. While this is fine in most instances, there may be situations in which you might, for example, wish the error messages not to be printed to the screen, but rather into a file, so that you could check later what has gone wrong. An additional motivation could come from the fact that, for any error occurring in a Windows program, a message box is displayed and program execution interrupted until you acknowledge having taken notice of the error.
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.
Except for the data-type conversion functions, only the float / fComplex / fPolar syntax is given. The syntax of the functions for double and extended precisions is exactly analogous.
If you chose the "classic" class complex, this is also similar. Just replace "float" by "double" and "fComplex" by "complex". No polar functions are available in the "classic" class complex, neither do any of the type-casting operators and interconversion functions exist, if there is only one type.
For the functions of double / dComplex / dPolar and extended / eComplex / ePolar precision, the prefixes are cd_, pd_, ce_, and pe_, respectively. The duality of Delphi functions (result returned) and procedures (result stored in variable) ows its existence to historic reasons, namely that early versions of Delphi die not support complex return values. Both forms are, however, completely equivalent.