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.
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.
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 |
| 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 |
| 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 |
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.
PGI 16.3-0 does not support complex arguments to inverse hyperbolic functions: ACOSH, ASINH, ATANH:
PGF90-S-0074-Illegal number or type of arguments to acosh - keyword argument x PGF90-S-0074-Illegal number or type of arguments to asinh - keyword argument x PGF90-S-0074-Illegal number or type of arguments to atanh - keyword argument x
Note that : "As of compiler version 17.0 (Intel Parallel Studio XE 2017), the significant Fortran 2008 features not yet supported are: ... Complex arguments to ACOS, ACOSH, ASIN, ASINH, ATAN, ATANH...", from Intel Fortran Compiler - Support for Fortran language standards, Updated October 14, 2016.
Oracle 12.5 doesn't yet support real32, real64, real128 named constants in iso_fortran_env. Also, complex arguments are not supported for inverse trigonometric functions: ACOS, ASIN, ATAN:
ERROR: Incorrect type/attribute of actual argument number 1 in generic procedure call "ACOS". ERROR: Incorrect type/attribute of actual argument number 1 in generic procedure call "ASIN". ERROR: Incorrect type/attribute of actual argument number 1 in generic procedure call "ATAN".
ACOSH, ASINH, ATANH tests give FPE.
In addition to the Oracle note above, real128 ACOSH, ASINH, ATANH are not supported yet:
ERROR: COMPLEX*32 intrinsic ACOSH is a Fortran 2008 feature which is not yet implemented. ERROR: COMPLEX*32 intrinsic ASINH is a Fortran 2008 feature which is not yet implemented. ERROR: COMPLEX*32 intrinsic ATANH is a Fortran 2008 feature which is not yet implemented.