CMPLX: Fortran 2008 complex intrinsics on branch cuts

Download CMPLX Download CMPLX
Download CMPLX
Download CMPLX

  1. What is this about?
  2. How to build/run?
  3. Test results

What is this about?

The values of complex functions on branch cuts are important, e.g. in fracture, fluid dynamics or elasticity in general, where the most important data is always on boundaries. Another example is the error function, erf(z), used extensively e.g. in acoustics. erf(z) is calculated using SQRT of complex arguments, including on the branch cut. Given that Fortran is still the most widely used language in science and engineering, particularly in HPC, this project focusses on testing the quality of implementation of Fortran complex intrinsics on branch cuts.

Fortran intrinsics LOG and SQRT accepted complex arguments at least since FORTRAN66. Fortran 2003 standard added support for the IEEE 754 floating point standard (ISO/IEC 60559), which defines minus zero and rules for its use. Fortran 2008 standard added support for complex arguments in intrinsic functions ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH. Fortran 2008 should therefore be suitable for calculations of the 8 elementary complex functions on branch cuts.

For more details of the package refer to A Shterenlikht, "On Quality of Implementation of Fortran 2008 Complex Intrinsic Functions on Branch Cuts", ACM Transactions on Mathematical Software, Vol. 45, No. 1, https://dl.acm.org/doi/10.1145/3301318, or the preprint: arXiv:1712.10230. For an in depth analysis of numerical algorithms for calculating these functions refer to W. Kahan, Branch Cuts for Complex Elementary Functions, or Much Ado About Nothing's Sign Bit, in The State of the Art in Numerical Analysis, A. Iserles, M. J. D. Powell Eds., Clarendon Press, Oxford, 1987 (PDF). The most authoritative information on the mathematics is probably DLMF, specifically Sections 4.2(i) The Logarithm for LOG, 4.23 Inverse Trigonometric Functions for ACOS, ASIN, ATAN and 4.37 Inverse Hyperbolic Functions for ACOSH, ASINH, ATANH.

CMPLX package is distributed under BSD license. With any questions, bug reports, feedback and any other comments please submit a ticket.

How to build/run?

Refer to README for more info. We use autotools (automake 1.16.1), so the basic build and test process is:

./configure
make
make check

The kind of real and complex variables is controlled by REAL_KIND environment variable. REAL_KIND=real64 will use IEEE binary64 real type. REAL_KIND=real128 will use IEEE binary128 real type. If REAL_KIND is not used, or given any other value, than IEEE binary32 real type will be used.

Non-default compiler flags are likely needed for any compiler to force strict IEEE conformance. Some examples of configure options (see README for more details):

./configure FC=gfortran8 FCFLAGS="-Wall -g -fsign-zero" LDFLAGS=-Wl,-rpath=/usr/local/lib/gcc8 REAL_KIND=real128
./configure FC=flang     FCFLAGS="-Minform=warn -Wall -Kieee -I/usr/local/flang/include" LDFLAGS="-lm" REAL_KIND=real64
./configure FC=ifort     FCFLAGS="-warn all -g -assume minus0 -fp-model precise"
./configure FC=ftn       FCFLAGS="-hfp0 -eacFn -dm -m2 -rl" REAL_KIND=real64
./configure FC=sunf90    FCFLAGS="-w3 -fsimple=0 -ftrap=none"
./configure FC=pgf90     FCFLAGS="-Minform=warn -Kieee -Ktrap=none" REAL_KIND=real32
./configure FC=xlf       FCFLAGS="-qstrict" REAL_KIND=real64
./configure FC=nagfor    FCFLAGS="-ieee=full"

Depending on the version of automake, the results of make check will be dumped on stdout or to the src/term*.log. The exact log file name will depend on the compiler.

In addition, if --with-gnuplot option is used to configure, conformal maps of the branch cuts of the 8 complex intrinsics will be plotted with gnuplot, from which a PDF report will be created automatically with latex. This will not succeed unless gnuplot, latex, dvips and ps2pdf are installed on the system. The report is saved in with_gnuplot/map*.pdf. For example, here's a PDF report produced with gfortran8 using REAL_KIND=real64.

Test results

13-MAY-2020

Some results from MS Windows, thanks to Arjen Markus. These include Intel compiler for MS Windows and GCC under Cygwin and under MinGW.

Compiler Version Platform REAL32 pass rate REAL64 pass rate REAL128 pass rate
GCC (gfortran) 9.3.0 Cygwin Kaby Lake 23/96 23/96 96/96
Intel (ifort) 18.0.5 MS Windows Kaby Lake 96/96 88/96 88/96
GCC (gfortran) 7.0.3 MinGW Kaby Lake 68/96 68/96 76/96

26-APR-2020 - cmplx-6

Compiler Version Platform REAL32 pass rate REAL64 pass rate REAL128 pass rate
GCC (gfortran) 10.0.1 FreeBSD Haswell 96/96 96/96 96/96
Flang (flang) 7.0.1 FreeBSD Haswell 51/58 51/58 Not supported

8-AUG-2018

Compiler Version Platform REAL32 pass rate REAL64 pass rate REAL128 pass rate
GCC (gfortran) 8.2.0 FreeBSD Haswell 96/96 96/96 76/96
Flang (flang) 5.0.2 FreeBSD Haswell 45/58 45/58 Not supported
Cray (ftn) 8.6.5 linux IvyBridge 67/96 66/96 76/96
Oracle/Sun (sunf95) 12.6 linux SandyBridge 44/56 42/56 18/18
PGI (pgfortran) 18.4 linux SandyBridge 42/58 42/58 Not supported
Intel (ifort) 18.0.3 linux Broadwell 96/96 96/96 96/96
IBM (xlf2008) 16.1.0 linux POWER8 67/96 66/96 Not supported
NAG (nagfor) 6.2 (6214) linux Broadwell 53/96 53/96 Not supported

8-JAN-2018

The analytical derivations are in doc.pdf. Conformal maps calculated with gfortran7 and plotted with PGPLOT are in res_pgplot.pdf. Conformal maps from Cray are in res_groff.pdf.

real32

real64

real128

2017

real32

real64

real128

Other Fortran related projects

validate this page