CLN, a Class Library for Numbers

CLN

This manual documents cln, a Class Library for Numbers.

Published by Bruno Haible, <haible@clisp.cons.org> and Richard B. Kreckel, <kreckel@ginac.de>.

Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008. Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009. Copyright (C) Alexei Sheplyakov 2008.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.

--- The Detailed Node Listing ---

Installation

Prerequisites

Building the library

Ordinary number types

Functions on numbers

Constructing numbers

Transcendental functions

Functions on integers

Conversion functions

Input/Output

Modular integers

Symbolic data types

Univariate polynomials

Internals

Using the library

Customizing

Next: Installation, Previous: Top, Up: Top

1 Introduction

CLN is a library for computations with all kinds of numbers. It has a rich set of number classes:

Integers (with unlimited precision),
Rational numbers,
Floating-point numbers:
- Short float,
- Single float,
- Double float,
- Long float (with unlimited precision),
Complex numbers,
Modular integers (integers modulo a fixed integer),
Univariate polynomials.

The subtypes of the complex numbers among these are exactly the types of numbers known to the Common Lisp language. Therefore CLN can be used for Common Lisp implementations, giving ‘CLN’ another meaning: it becomes an abbreviation of “Common Lisp Numbers”.

The CLN package implements

Elementary functions (+, -, *, /, sqrt, comparisons, ...),
Logical functions (logical and, or, not, ...),
Transcendental functions (exponential, logarithmic, trigonometric, hyperbolic functions and their inverse functions).

CLN is a C++ library. Using C++ as an implementation language provides

efficiency: it compiles to machine code,
type safety: the C++ compiler knows about the number types and complains if, for example, you try to assign a float to an integer variable.
algebraic syntax: You can use the +, -, *, =, ==, ... operators as in C or C++.

CLN is memory efficient:

Small integers and short floats are immediate, not heap allocated.
Heap-allocated memory is reclaimed through an automatic, non-interruptive garbage collection.

CLN is speed efficient:

The kernel of CLN has been written in assembly language for some CPUs (i386, m68k, sparc, mips, arm).
On all CPUs, CLN may be configured to use the superefficient low-level routines from GNU GMP version 3.
It uses Karatsuba multiplication, which is significantly faster for large numbers than the standard multiplication algorithm.
For very large numbers (more than 12000 decimal digits), it uses multiplication, which is an asymptotically optimal multiplication algorithm, for multiplication, division and radix conversion.
It uses binary splitting for fast evaluation of series of rational numbers as they occur in the evaluation of elementary functions and some constants.

CLN aims at being easily integrated into larger software packages:

The garbage collection imposes no burden on the main application.
The library provides hooks for memory allocation and throws exceptions in case of errors.
All non-macro identifiers are hidden in namespace cln in order to avoid name clashes.

Next: Ordinary number types, Previous: Introduction, Up: Top

2 Installation

This section describes how to install the CLN package on your system.

Next: Building the library, Previous: Installation, Up: Installation

2.1 Prerequisites

Next: Make utility, Up: Prerequisites

2.1.1 C++ compiler

To build CLN, you need a C++ compiler. Actually, you need GNU g++ 3.0.0 or newer.

The following C++ features are used: classes, member functions, overloading of functions and operators, constructors and destructors, inline, const, multiple inheritance, templates and namespaces.

The following C++ features are not used: new, delete, virtual inheritance.

CLN relies on semi-automatic ordering of initializations of static and global variables, a feature which I could implement for GNU g++ only. Also, it is not known whether this semi-automatic ordering works on all platforms when a non-GNU assembler is being used.

Next: Sed utility, Previous: C++ compiler, Up: Prerequisites

2.1.2 Make utility

To build CLN, you also need to have GNU make installed.

Only GNU make 3.77 is unusable for CLN; other versions work fine.

Previous: Make utility, Up: Prerequisites

2.1.3 Sed utility

To build CLN on HP-UX, you also need to have GNU sed installed. This is because the libtool script, which creates the CLN library, relies on sed, and the vendor's sed utility on these systems is too limited.

Next: Installing the library, Previous: Prerequisites, Up: Installation

2.2 Building the library

As with any autoconfiguring GNU software, installation is as easy as this:

     $ ./configure
     $ make
     $ make check

If on your system, ‘make’ is not GNU make, you have to use ‘gmake’ instead of ‘make’ above.

The configure command checks out some features of your system and C++ compiler and builds the Makefiles. The make command builds the library. This step may take about half an hour on an average workstation. The make check runs some test to check that no important subroutine has been miscompiled.

The configure command accepts options. To get a summary of them, try

     $ ./configure --help

Some of the options are explained in detail in the ‘INSTALL.generic’ file.

You can specify the C compiler, the C++ compiler and their options through the following environment variables when running configure:

CC: Specifies the C compiler.
CFLAGS: Flags to be given to the C compiler when compiling programs (not when linking).
CXX: Specifies the C++ compiler.
CXXFLAGS: Flags to be given to the C++ compiler when compiling programs (not when linking).
CPPFLAGS: Flags to be given to the C/C++ preprocessor.
LDFLAGS: Flags to be given to the linker.

Examples:

     $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure

     $ CC="gcc -V 3.2.3" CFLAGS="-O2 -finline-limit=1000" \
       CXX="g++ -V 3.2.3" CXXFLAGS="-O2 -finline-limit=1000" \
       CPPFLAGS="-DNO_ASM" ./configure

     $ CC="gcc-4.2" CFLAGS="-O2" CXX="g++-4.2" CXXFLAGS="-O2" ./configure

Note that for these environment variables to take effect, you have to set them (assuming a Bourne-compatible shell) on the same line as the configure command. If you made the settings in earlier shell commands, you have to export the environment variables before calling configure. In a csh shell, you have to use the ‘setenv’ command for setting each of the environment variables.

Currently CLN works only with the GNU g++ compiler, and only in optimizing mode. So you should specify at least -O in the CXXFLAGS, or no CXXFLAGS at all. If CXXFLAGS is not set, CLN will be compiled with -O.

The assembler language kernel can be turned off by specifying -DNO_ASM in the CPPFLAGS. If make check reports any problems, you may try to clean up (see Cleaning up) and configure and compile again, this time with -DNO_ASM.

If you use g++ 3.2.x or earlier, I recommend adding ‘-finline-limit=1000’ to the CXXFLAGS. This is essential for good code.

If you use g++ from gcc-3.0.4 or older on Sparc, add either ‘-O’, ‘-O1’ or ‘-O2 -fno-schedule-insns’ to the CXXFLAGS. With full ‘-O2’, g++ miscompiles the division routines. Also, do not use gcc-3.0 on Sparc for compiling CLN, it won't work at all.

Also, please do not mpiles the division routines. Also, do not use gcc-3.0 on Sparc for compiling CLN, it won't work at all.

Also, please do not mpiles the division routines.