V3.80: fleshing out double-double and quad-double (#443)

* Setting SEMVER to v3.80

* refining numeric_limits for quad-double

* update headers with license SPDX

* adding quad-double command line utility

* adding a double-double command line utility

* refining numeric_limits for double-double

* WIP: implementing nextafter for double-double

* bug fix on the incorrectly modified ulp() function on native ieee754 floating-point numbers

* WIP: isolate double free bug in dd::to_string

* WIP: found a bug in fixed format to_string for double-double

* memory management bug fix in dd::to_string

* bug fix memory corruption in round_string

* unifying the std::ostream precision articulation

* first principle construction of double-double and quad-double values

* adding an double-double ulp test case

* bug fix fixpnt conversion of real values smaller than half of minpos

* updating fixpnt cli command with universal type name and new types

* WIP: still trying to deduce the ulp algorithm for double-double

* double-double ulp function

* code hygiene and creating a string_utils.hpp to collect string utilities

* header updates

* implementation of increment and decrement

* WIP: printing a double-double in fixed form destroys a leading zero

* dd code hygiene, qd api test progression

* WIP: first implementation of increment and decrement for quad-double

* WIP: implementing extreme value API for quad-double

* code hygiene: isolating internal::uint128 so bitblock is not part of double-double or quad-double dependencies

* code hygiene qd: removing signed/unsigned index warnings in decimal string generation

* adding a verification suite to pow() function for double-double

* moving error_free_ops.hpp from native to numerics to keep ieee754.hpp lightweight

* compilation fix for GCC

* MSVC fix: std::isfinite() is not yet constexpr

* Restructuring build process to isolate projects that depend on complex<>

* bringing together all the complex<> regression suites into a consistent build flow

* resolving all the missing inline keywords on the dd and qd math functions

* Adding new ArXiv publication on iterative refinement with low-precision posits

* unifying the to_components formatting between dd and qd types

* implementing ulp() and to_binary() for quad-double

* adding a math function extension mechanism so we can start experimenting with non-elemental functions

* streamlining Horner's rule functionality across Universal

* compilation fix for gcc/clang

* code hygiene and AppleClang build restructuring

* creating the first design structure to manage a generic math function library

* organizing constants and complex in math library

* compilation fix for gcc/clang

* simpler build configuration for complex<>

* adding native quad-double trigonometry function approximations

* unifying the constexpr table vars with regular dd and qd constants

* removal of files no longer required for dd

* settling on a naming convention for the mathematical constants that is consistent across types

* preparing double-double math infrastructure to mimic universal/math structure

* completing generation of quad-double constants and math library structure

* tracking precision difference between Debug and Release builds in quad-double

* forgot to save the test src

* adding Apple M2 silicon results

* WIP: trying out cbrt as a test math function for specialization with generics fallback

* adding compile-time messages for non-MSVC compilers

* removing warnings on qd_inverse_factorial_table_size int/unsigned mismatch

* code hygiene

.devcontainer/devcontainer.json

@@ -1,3 +1,3 @@
 {
-	"image": "stillwater/builders:clang18builder"
+	"image": "stillwater/builders:clang16builder"
 }

.github/workflows/cmake.yml

@@ -2,7 +2,7 @@ name: CMake
 
 on:
   push:
-    branches: [ v3.79, dev, main ]
+    branches: [ v3.80, dev, main ]
   pull_request:
     branches: [ main ]
 

.gitignore

@@ -6,6 +6,10 @@ build
 build_msvc
 build_gcc
 build_clang
+build_apple
+
+# CMake ctest directoreis
+Testing
 
 # CLion IDE config caches
 .idea

CMakeLists.txt

@@ -25,7 +25,7 @@ if(NOT DEFINED UNIVERSAL_VERSION_MAJOR)
   set(UNIVERSAL_VERSION_MAJOR 3)
 endif()
 if(NOT DEFINED UNIVERSAL_VERSION_MINOR)
-  set(UNIVERSAL_VERSION_MINOR 79)
+  set(UNIVERSAL_VERSION_MINOR 80)
 endif()
 if(NOT DEFINED UNIVERSAL_VERSION_PATCH)
   set(UNIVERSAL_VERSION_PATCH 1)
@@ -89,6 +89,7 @@ option(BUILD_NUMBERS                     "Set to ON to build all the number syst
 option(BUILD_NUMERICS                    "Set to ON to build all the numeric components"       OFF)
 option(BUILD_BENCHMARKS                  "Set to ON to build all the benchmark components"     OFF)
 option(BUILD_MIXEDPRECISION_SDK          "Set to ON to build the mixed-precision SDK"          OFF)
+option(BUILD_COMPLEX                     "Set to ON to build complex support components"       OFF)
 
 # or, build individual components
 # utilities and educational examples
@@ -606,6 +607,8 @@ if(BUILD_ALL)
 	set(BUILD_NUMBERS ON)
 	set(BUILD_MIXEDPRECISION_SDK ON)
 	set(BUILD_APP_ENVIRONMENT ON)
+# for the moment, explicitely turn COMPLEX off until we have a standalone complex<> solution
+	set(BUILD_COMPLEX OFF)
 
 	# build the BLAS test/verification suites
 	set(BUILD_LINEAR_ALGEBRA_BLAS ON)
@@ -620,13 +623,16 @@ if(BUILD_ALL)
 	set(BUILD_VALIDATION_HW ON)
 endif(BUILD_ALL)
 
-# set the grouped components to build (will trigger builds when tested)
+# set the grouped components to build Continuous Integration regression suite
+# we are disabling COMPLEX because we need a solution to the 
+# disappearing support of complex<> for user-defined types
 if(BUILD_CI)
 	set(BUILD_NUMBERS ON)
 	set(BUILD_DEMONSTRATION OFF)
 	set(BUILD_NUMERICS OFF)
 	set(BUILD_MIXEDPRECISION_SDK OFF)
 	set(BUILD_APP_ENVIRONMENT ON)
+	set(BUILD_COMPLEX OFF)
 endif(BUILD_CI)
 
 # core demonstration example applications that use the library
@@ -637,6 +643,21 @@ if(BUILD_DEMONSTRATION)
 	set(BUILD_PLAYGROUND ON)
 endif(BUILD_DEMONSTRATION)
 
+# enable complex environment components
+if(BUILD_COMPLEX)
+# right now, the complex arithmetic and math functions (imag, real, conj)
+# are maintained in the individual number system regression suites.
+# Their respective build systems will use BUILD_COMPLEX to add/remove
+# the complex<> regression suites.
+	set(BUILD_APPLICATIONS ON)
+	set(BUILD_NUMBER_FIXPNTS ON)
+	set(BUILD_NUMBER_CFLOATS ON)
+	set(BUILD_NUMBER_POSITS ON)
+# I am leaving this segment here as a pattern that might drive the development
+# of a complex<> replacement that might need its own regression suite 
+# independent of user-defined types.
+endif(BUILD_COMPLEX)
+
 if(BUILD_NUMBERS)
 	# build the different test/verification suites for each number system
 	set(BUILD_NUMBER_INTERNALS ON)

README.md

@@ -60,9 +60,24 @@ The library contains fast implementations of special IEEE-754 formats that do no
 
 ## Citation
 
-Please cite [our work](https://arxiv.org/abs/2012.11011) if you use *Universal*.
+Please cite [our work](https://joss.theoj.org/papers/10.21105/joss.05072) if you use *Universal*.
 
+Research results using *Universal* arithmetic types are also available:
+1. [Reproducibility](https://arxiv.org/abs/2012.11011)
+2. [Iterative Refinement](https://arxiv.org/abs/2408.13400)
+
+Lorenz System ODE solver using low-precision posits:
+![visual-studio-project](docs/img/Lorenz-system.png)
+
+## Bibtex records
 ```bib
+@article{Quinlan:2024,
+    author     = {James Quinlan, E. Theodore L. Omtzigt},
+    title      = {Iterative Refinement with Low-Precision Posits},
+    journal    = {arXiv:2408.13400},
+    year       = {2024},
+}
+
 @article{omtzigt2023universal,
   title={Universal Numbers Library: Multi-format Variable Precision Arithmetic Library},
   author={Omtzigt, E Theodore L and Quinlan, James},

applications/mixed-precision/dnn/fit_sin.cpp

@@ -1,6 +1,7 @@
 // fit_sin.cpp: fit y = sin(x) with a third order polynomial using gradient descent
 //
 // Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
@@ -11,7 +12,7 @@
 #include <universal/number/lns/lns.hpp>
 #include <universal/blas/blas.hpp>
 #include <universal/dnn/dnn.hpp>
-#include <universal/math/math_constants.hpp>
+#include <universal/math/constants/double_constants.hpp>
 
 /*
 We will use a problem of fitting the function y=sin(x) with a third order polynomial as our example.
@@ -31,7 +32,7 @@ void SinFunctionFit() {
 
 	Vector x(nrSamples), y(nrSamples), y_pred(nrSamples);
 	// create linear samples between -pi and pi
-	x = blas::linspace(-m_pi, m_pi, nrSamples);  // we create a vector<double> due to m_pi and then assign to vector<Scalar>
+	x = blas::linspace(-d_pi, d_pi, nrSamples);  // we create a vector<double> due to d_pi and then assign to vector<Scalar>
 	y = blas::sin(x);
 
 	// model parameters

applications/performance/complex/CMakeLists.txt

@@ -1,14 +1,9 @@
 file (GLOB SOURCES "./*.cpp")
 
-# Compiler specific environments
-# message(STATUS "CMAKE_CXX_COMPILER ID is -${CMAKE_CXX_COMPILER_ID}-")
-
 # exclude AppleClang as XCode14 and Xcode15 have std::complex libs that do not support user defined types5
-if(CMAKE_CXX_COMPILER_ID MATCHES  "AppleClang")
-    message(STATUS "Ignoring complex tests for AppleClang")
-
-else()
-    message(STATUS "Adding complex test for all other non-AppleClang environments")
-    compile_all("true" "complex" "Applications/Performance/Complex" "${SOURCES}")
-
-endif()
+if(BUILD_COMPLEX)
+	message(STATUS "Adding complex test for Application environment")
+	compile_all("true" "complex" "Complex/Applications/Performance" "${SOURCES}")
+else(BUILD_COMPLEX)
+	message(STATUS "Ignoring complex tests for application/performance")
+endif(BUILD_COMPLEX)

applications/performance/complex/compute.cpp

@@ -1,6 +1,7 @@
 // compute.cpp: experiments with complex real/imaginary computations
 //
-// Copyright (C) 2017-2021 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal number project, which is released under an MIT Open Source license.
 #include <math.h>
@@ -32,7 +33,7 @@
 // second: enable/disable posit arithmetic exceptions
 #define POSIT_THROW_ARITHMETIC_EXCEPTION 1
 #include <universal/number/posit/posit.hpp>
-#include <universal/math/complex_manipulators.hpp>  // to_binary() for complex types
+#include <universal/math/complex/manipulators.hpp>  // to_binary() for complex types
 
 
 template<typename Scalar>

applications/precision/math/pascals_triangle.cpp

@@ -12,7 +12,7 @@
 // enable posit arithmetic exceptions
 #define POSIT_THROW_ARITHMETIC_EXCEPTION 1
 #include <universal/number/posit/posit.hpp>
-#include <universal/functions/binomial.hpp>
+#include <universal/math/functions/binomial.hpp>
 
 std::string spacing(int n) {
 	std::stringstream ss;

applications/precision/math/stirlings_approximation.cpp

@@ -13,7 +13,7 @@
 #include <universal/native/ieee754.hpp>
 #include <universal/number/edecimal/edecimal.hpp> // the oracle number system to use
 #include <universal/number/posit/posit.hpp>
-#include <universal/functions/factorial.hpp>
+#include <universal/math/functions/factorial.hpp>
 
 #include <universal/utility/error.hpp>
 

applications/reproducibility/blas/inverse.cpp

@@ -5,17 +5,14 @@
 //
 // This file is part of the HPRBLAS project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
-
 #include <chrono>
-
 // enable posit arithmetic exceptions
 #define POSIT_THROW_ARITHMETIC_EXCEPTION 1
 // enable fast posits
 #define POSIT_FAST_SPECIALIZATION
 #include <universal/number/posit/posit.hpp>
 #include <universal/blas/blas.hpp>
 #include <universal/blas/generators.hpp>
-#include <universal/functions/isrepresentable.hpp>
 
 template<typename Matrix, typename Vector>
 void BenchmarkGaussJordan(const Matrix& A, Vector& x, const Vector& b) {

applications/reproducibility/blas/lu.cpp

@@ -6,8 +6,6 @@
 // This file is part of the HPRBLAS project, which is released under an MIT Open Source license.
 #include <chrono>
 #include <universal/utility/directives.hpp>
-#include <universal/functions/isrepresentable.hpp>
-
 #include <universal/native/ieee754.hpp>
 // enable posit arithmetic exceptions
 #define POSIT_THROW_ARITHMETIC_EXCEPTION 1

benchmark/performance/arithmetic/areal/performance.cpp

@@ -1,6 +1,7 @@
 // performance.cpp : performance benchmarking for abitrary fixed-precision reals
 //
-// Copyright (C) 2017-2021 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <iostream>
@@ -9,8 +10,6 @@
 // configure the areal arithmetic class
 #define AREAL_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/areal/areal.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/cfloat/performance.cpp

@@ -1,15 +1,14 @@
-// performance.cpp : performance benchmarking for abitrary fixed-precision cfloats
+// performance.cpp : performance benchmarking for arbitrary fixed-precision cfloats
 //
-// Copyright (C) 2017-2021 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
 #include <chrono>
 // configure the cfloat arithmetic class
-#define cfloat_THROW_ARITHMETIC_EXCEPTION 0
+#define CFLOAT_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/cfloat/cfloat.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/compare/performance.cpp

@@ -1,6 +1,7 @@
 // performance.cpp : performance benchmarking for native floating-point
 //
-// Copyright (C) 2017-2021 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
@@ -19,8 +20,6 @@
 #define POSIT_FAST_POSIT_16_1 1
 #define POSIT_FAST_POSIT_32_2 1
 #include <universal/number/posit/posit.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_suite.hpp>
 #include <universal/benchmark/performance_runner.hpp>
 
@@ -42,10 +41,6 @@ void CopyWorkload(size_t NR_OPS) {
 	if (bFail) std::cout << "COPY FAIL\n"; // just a quick double check that all went well
 }
 
-/* 
-
-*/
-
 /// <summary>
 /// measure performance of copying numbers around
 /// </summary>

benchmark/performance/arithmetic/decimal/performance.cpp

@@ -1,6 +1,7 @@
 // performance.cpp : performance benchmarking for adaptive precision decimal integers
 //
-// Copyright (C) 2017-2023 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
@@ -10,8 +11,6 @@
 // configure the decimal arithmetic class
 #define EDECIMAL_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/edecimal/edecimal.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/fixpnt/performance.cpp

@@ -1,4 +1,4 @@
-//  performance.cpp : performance benchmarking for fixed-sized, abitrary precision fixpnts
+//  performance.cpp : performance benchmarking for fixed-sized, arbitrary precision fixpnts
 //
 // Copyright (C) 2017-2022 Stillwater Supercomputing, Inc.
 //
@@ -9,9 +9,6 @@
 // configure the fixpnt arithmetic class
 #define INTEGER_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/fixpnt/fixpnt.hpp>
-#include <universal/number/fixpnt/numeric_limits.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/integer/performance.cpp

@@ -1,6 +1,7 @@
-//  performance.cpp : performance benchmarking for abitrary precision integers
+//  performance.cpp : performance benchmarking for fixed-sized, arbitrary precision integers
 //
-// Copyright (C) 2017-2021 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
@@ -10,9 +11,6 @@
 // configure the integer arithmetic class
 #define INTEGER_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/integer/integer.hpp>
-#include <universal/number/integer/numeric_limits.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/lns/performance.cpp

@@ -1,6 +1,7 @@
 // performance.cpp : performance benchmarking for abitrary fixed-precision logarithmic numbers
 //
-// Copyright (C) 2017-2022 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <iostream>
@@ -9,8 +10,6 @@
 // configure the arithmetic class
 #define LNS_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/lns/lns.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/native/performance.cpp

@@ -12,7 +12,7 @@
 
 #include <universal/native/ieee754.hpp>
 // is representable
-#include <universal/functions/isrepresentable.hpp>
+#include <universal/math/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>
 

benchmark/performance/arithmetic/unum/performance.cpp

@@ -1,15 +1,14 @@
 // performance.cpp : performance benchmarking for adaptive precision universal numbers (unum Type 1)
 //
-// Copyright (C) 2017-2021 Stillwater Supercomputing, Inc.
+// Copyright (C) 2017 Stillwater Supercomputing, Inc.
+// SPDX-License-Identifier: MIT
 //
 // This file is part of the universal numbers project, which is released under an MIT Open Source license.
 #include <universal/utility/directives.hpp>
 #include <chrono>
 // configure the arithmetic class
 #define UNUM_THROW_ARITHMETIC_EXCEPTION 0
 #include <universal/number/unum/unum.hpp>
-// is representable
-#include <universal/functions/isrepresentable.hpp>
 #include <universal/verification/test_status.hpp> // ReportTestResult
 #include <universal/benchmark/performance_runner.hpp>