#

A Tour of NTL: NTL Implementation and Portability

NTL is designed to be portable, fast, and relatively easy to use and extend.

To make NTL portable, no assembly code is used (well, almost none, see below). This is highly desirable, as architectures are constantly changing and evolving, and maintaining assembly code is quite costly. By avoiding assembly code, NTL should remain usable, with virtually no maintenance, for many years.

### Minimal platform requirements

When the configuration flags `NTL_CLEAN_INT` and `NTL_CLEAN_PTR` are both on (this is not the default, see below), NTL makes two requirements of its platform, neither of which are guaranteed by the `C++` language definition, but are essentially universal:

1. `int` and `long` quantities, respectively, are represented using a 2's complement representation whose width is equal to the width of `unsigned int` and `unsigned long`, respectively.
2. Double precision floating point conforms to the IEEE floating point standard.

NTL makes very conservative requirements of the `C++` compiler:

- it is assumed that the `C++` compiler conforms to the 1998 standard, including the basic of templates;
- it does not assume any features not in the 1998 standard, unless compiled with the `NTL_THREADS` or `NTL_EXCEPTIONS` flags.

### The `NTL_CLEAN_INT` flag

The configuration flag `NTL_CLEAN_INT` is currently off by default.

When this flag is off, NTL makes another requirement of its platform; namely, that conversions from `unsigned long` to `long` convert the bit pattern without change to the corresponding 2's complement signed integer. Note that the `C++` standard defines the behavior of converting unsigned to signed values as implementation defined when the value cannot be represented in the range of nonnegative signed values. Nevertheless, this behavior is essentially universal, and more importantly, is is not undefined behavior: implementation-defined behavior must be documented and respected by the compiler, while undefined behavior can be exploited by the compiler in some surprising ways.

Actually, with `NTL_CLEAN_INT` off, it is also assumed that right shifts of signed integers are consistent, in the sense that if it is sometimes an arithmetic shift, then it is always an arithmetic shift (the installation scripts check if right shift appears to be arithmetic, and if so, this assumption is made elsewhere). Arithmetic right shift is also implementation defined behavior that is essentially universal.

It seems fairly unlikely that one would ever have to turn the `NTL_CLEAN_INT` flag on, but it seems a good idea to make this possible, and at the very least to identify and isolate the code that relies on this assumption. The only code affected by this flag is the traditional LIP long integer package (which, if you use GMP as the long integer package, is not involved), and the single-precision modular multiplication routines.

Note that prior to NTL 9.0, the default compilation mode required that in a few critical places, signed integer arithmetic quietly wraps around on overflow; however, signed integer overflow is undefined behavior, and it seems that in recent years compilers have been getting more aggressive in exploiting such undefined behavior in their optimizations. Moreover, recent versions of GCC now come with a "sanitizer" that checks for undefined behavior. So, both to avoid potentially dangerous optimizations and to allow NTL to pass such sanitzer checks, it seemed safer to move to this more conservative approach. There should, in fact, be zero performance penalty in doing so. Also note that I was never aware of any compiler that generated incorrect code in the pre-9.0 code: this new approach is just to be on the safe side in the future.

### The `NTL_CLEAN_PTR` flag

The configuration flag `NTL_CLEAN_PTR` is currently off by default.

When this flag is off, NTL makes another requirement of its platform; namely, that the address space is "flat", and in particular, that one can test if an object pointed to by a pointer `p` is located in a array of objects `v[0..n-1]` by testing if `p >= v` and `p < v + n`. The `C++` standard does not guarantee that such a test will work; the only way to perform this test in a standard-conforming way is to iteratively test if `p == v`, `p == v+1`, etc.

This assumption of a "flat" address space is essentially universally valid, and making this assumption leads to more efficicient code. For this reason, the `NTL_CLEAN_PTR` is off by default, but one can always turn it on, and in fact, the overall performance penalty should be negligible for most applications.

### Some floating point issues

NTL uses floating point arithmetic in a number of places, including a number of exact computations, where one might not expect to see floating point. Relying on floating point may seem prone to errors, but with the guarantees provided by the IEEE standard, one can prove the correctness of the NTL code that uses floating point.

Briefly, the IEEE floating point standard says that basic arithmetic operations on doubles should work as if the operation were performed with infinite precision, and then rounded to `p` bits, where `p` is the precision (typically, `p = 53`).

Throughout most of NTL, correctness follows from weaker assumptions, namely

- basic arithmetic operations and conversion from integral types produce results with a relative error of `2^{-p + 1}` (assuming no overflow),
- multiplication by powers of 2 produce exact results (assuming no overflow),
- basic arithmetic operations on integers represented as doubles and conversions from integral types to doubles produce exact results, provided the inputs and outputs are less than `2^p` in absolute value,
- if `y/2 <= x <= 2y`, then `x-y` is computed exactly.

Also, NTL allows the compiler to compute `z = x/y` as `t = 1/y`, `z = t*x`.

It is also generally assumed that the compiler does not do too much "regrouping" of arithmetic expressions involving floating point. Most compilers respect the implied grouping of floating point computations, and NTL goes out of its way to make its intentions clear: instead of `x = (a + b) + c`, if the grouping is truly important, this is written as `t = a + b; x = t + c`. Current standards do not allow, and most implementations will not perform, any regrouping of this, e.g., `x = a + (b + c)`, since in floating point, addition and subtraction are not associative.

Unfortunately, some compilers do not do this correctly, unless you tell them. With Intel's C compiler `icc`, for example, you should compile NTL with the flag `-fp-model source` to enforce strict adherence to floating point standards. Also, you should be wary of compiling using an optimization level higher than the default `-O2` -- this may break some floating point assumptions (and maybe some other assumptions as well).

One big problem with the IEEE standard is that it allows intermediate quantities to be computed in a higher precision than the standard double precision. Most platforms today implement the "strict" IEEE standard, with no excess precision. Up until recently, the Intel x86 machine with the GCC compiler was a notable exception to this: on older x86 machines, floating point was performed using the x87 FPU instructions, which operate on 80-bit, extended precision numbers; nowadays, most compilers use the SSE instructions, which operate on the standard, 64-bit numbers.

Historically, NTL went out of its way to ensure that its code is correct with both "strict" and "loose" IEEE floating point. This is achieved in a portable fashion throughout NTL, except for the `quad_float` module, where some desperate hacks, including assembly code, may be used to try to work around problems created by "loose" IEEE floating point [more details]. But note that even if the `quad_float` package does not work correctly because of these problems, the only other routines that are affected are the `LLL_QP` routines in the `LLL` module -- the rest of NTL should work fine. Hopefully, because of the newer SSE instructions, this whole strict/loose issue is a thing of the past.

Mostly, NTL does not require that the IEEE floating point special quantities "infinity" and "not a number" are implemented correctly. This is certainly the case for core code where floating point arithmetic is used for exact (but fast) computations, as the numbers involved never get too big (or small). However, the behavior of certain explicit floating point computations (e.g., the `xdouble` and `quad_float` classes, and the floating point versions of LLL) will be much more predictable and reliable if "infinity" and "not a number" are implemented correctly.

### Implementing long integer arithmetic

There are two basic strategies for implementing long integer arithmetic.

The default strategy is implemented in the traditional long integer arithmetic package. This package is derived from the LIP package originally developed by A. K. Lenstra, although it has evolved quite a bit within NTL. This package uses no assembly code and is very portable.

The alternative strategy is to use GMP in place of LIP. In this strategy, the representation of long integers is in a form compatible with GMP. This strategy typically yields the best performance, but requires that GMP is installed on your platform.

Go here for more details on the use of GMP with NTL.

### Algorithms

NTL makes fairly consistent use of asymptotically fast algorithms.

Long integer multiplication is implemented using the classical algorithm, crossing over to Karatsuba for very big numbers. Long integer division is currently only implemented using the classical algorithm -- unless you use NTL with GMP (version 3 or later), which employs an algorithm that is about twice as slow as multiplication for very large numbers.

Polynomial multiplication and division is carried out using a combination of the classical algorithm, Karatsuba, the FFT using small primes, and the FFT using the Schoenhagge-Strassen approach. The choice of algorithm depends on the coefficient domain.

Many algorithms employed throughout NTL are inventions of the author (Victor Shoup) and his colleagues Joachim von zur Gathen and Erich Kaltofen, as well as John Abbott and Paul Zimmermann.

### Thread safety

As of v7.0, NTL is thread safe. That said, there are several things to be aware of:

- To use this feature, you have to enable `NTL_THREADS` in the configuration script. Also, you will need a compiler and runtime library that implements several key `C++11` features, including `thread_local` storage.

  Currently (October 2015), there are still few compilers that satisfy the requirements. I have been able to compile and run multithreaded code using gcc 4.9.2 on a Linux system. I have not been able to do so on any current Mac OSX system: in fact, no compiler on current Mac systems (gcc or clang) yet have proper support for `thread_local` storage.

- While extreme care has been taken with the design and implementation of thread safety, this feature is still fairly new and needs more stress testing.

- You must build NTL using GMP (i.e., configure with `NTL_GMP_LIP=on`). The classic LIP integer arithmetic is not thread safe: it could be made so, but it is not a priority at this time.

- The current version (v1.1) of the external gf2x library is not thread safe. Therefore, you should build NTL using gf2x if you need a thread-safe build.

To obtain thread safety, I used the following strategies:

- In places where NTL's interface demands global variables, such as the "current modulus" for the `ZZ_p` class, these global variables have been made thread local. So, you can pass around various `ZZ_pContext` objects among threads, and individual threads can install these locally. Thus, different threads can concurrently use the same or different moduli, and it all just works, with no changes to NTL's interface.

- In places where NTL used static variables to hold on to space for scratch variables, I make these variables thread local, and I also make sure the storage used by these variables get released when the thread terminates. In all NTL builds (thread safe or not), I try to make sure that fairly large chunks of memory get released immediately.

- In places where NTL uses a lazy strategy to build various tables (such as FFT primes), I uses a "double checked locking" strategy to grow these tables in a way that (a) the tables can be shared among different threads, and (b) taking a lock on a `mutex` is very rare. The new `C++11` concurrent memory model is essential here.

- Smart pointers (for things like `ZZ_pContext`'s) are designed to do the necesary reference counting in a thread-safe manner.

- For psuedo-random number generation, the internal state of the PRG is thread local, and the default initial seed is guaranteed to be unique among all threads in a given process (and an attempt is made to make the seed globally unique among all processes and threads, but this is hard to do in a completely portable way).

The overall structure of the code has been modified so that the code base is nearly identical for regular and thread-safe builds: there are just a few `ifdef`'s on the `NTL_THREADS` flag.

### Thread Boosting

As of v9.5.0, NTL provides a thread boosting feature. With this feature, certain code within NTL will use available threads to speed up computations on a multicore machine. This feature is enabled by setting `NTL_THREAD_BOOST=on` during configuration. See BasicThreadPool.txt for more information.

This feature is a work in progress. Currently, basic `ZZ_pX` arithmetic has been thread boosted. More code will be boosted later.

### Error Handling and Exceptions

As of v8.0, NTL provides error handling through exceptions. To enable exptions, you have to configure NTL with `NTL_EXCEPTIONS` flag turned on. By default, exceptions are not enabled, and NTL reverts to its old error handling method: abort with an error message.

If exceptions are enabled, then instead of aborting your program, and appropriate exception is thrown. More details ion the programming interface of this feature are available here.

If you enable exceptions, you must use a `C++11` compiler. Specifically, your compiler will need support for lambdas (which are used to conveniently implement the "scope guard" idiom), and your compiler should implement the new default exception specification semantics (namely, that destructors are "noexcept" by default).

Implementation of this required a top-to-bottom scrub of NTL's code, replacing a lot of old-fashioned code with more modern, RAII-oriented code (RAII = "resource acquisition is initialization").