NumTheory

© 2009 John Abbott
GNU Free Documentation License, Version 1.2



CoCoALib Documentation Index

User documentation

Generalities

The functions in the NumTheory file are predominantly basic operations from number theory. Most of the functions may be applied to machine integers or big integers (i.e. values of type BigInt). Please recall that computational number theory is not the primary remit of CoCoALib, so do not expect to find a complete collection of operations here -- you would do better to look at Victor Shoup's NTL (Number Theory Library), or PARI/GP, or some other specialized library/system.

Examples

The Functions Available For Use

Several of these functions give errors if they are handed unsuitable values: unless otherwise indicated below the error is of type ERR::BadArg. All functions expecting a modulus will throw an error if the modulus is less than 2 (or an unsigned long value too large to fit into a long).

The main functions available are:

Continued Fractions

Several of these functions give errors if they are handed unsuitable values: unless otherwise indicated below the error is of type ERR::BadArg.

Recall that any real number has an expansion as a continued fraction (e.g. see Hardy & Wright for definition and many properties). This expansion is finite for any rational number. We adopt the following conventions which guarantee that the expansion is unique:

For example, with these conventions the expansion of -7/3 is (-3, 1, 2).

The main functions available are:

Maintainer Documentation

Correctness of ExtendedEuclideanAlg is not immediately clear, because the cofactor variables could conceivably overflow -- in fact this cannot happen (at least on a binary computer): for a proof see Shoup's book A Computational Introduction to Number Theory and Algebra, in particular Theorem 4.3 and the comment immediately following it. There is just one line where a harmless "overflow" could occur -- it is commented in the code.

Several functions are more complicated than you might expect because I wanted them to be correct for all possible machine integer inputs (e.g. including the most negative long value).

In some cases the function which does all the work is implemented as a file local function operating on unsigned long values: the function should normally be used only via the "dispatch" functions whose args are of type MachineInt or BigInt.

The continued fractions functions are all pretty simple. The only tricky part is that the "end" of the ContFracIter is represented by both myFrac and myQuot being zero. This means that a newly created iterator for zero is already ended.

CFApproximantsIter delegates most of the work to ContFracIter.

Bugs, Shortcomings, etc.

Several functions return long values when perhaps unsigned long would possibly be better choice (since it offers a greater range, and in the case of gcd it would permit the fn to return a result always, rather than report "overflow"). The choice of return type was dictated by the coding conventions, which were in turn dictated by the risks of nasty surprises to unwary users unfamiliar with the foibles of unsigned values in C++.

Should there also be procedural forms of functions which return BigInt values? (e.g. gcd, lcm, InvMod, PowerMod, and so on).

Certain implementations of PowerMod should be improved (e.g. to use PowerModSmallModulus whenever possible). Is behaviour for 0^0 correct?

LucasTest should produce a certificate, and be made publicly accessible.

How should the cont frac iterators be printed out???

ContFracIter could be rather more efficient for rationals having very large numerator and denominator. One way would be to compute with num and den divided by the same large factor (probably a power of 2), and taking care to monitor how accurate these "scaled" num and den are. I'll wait until there is a real need before implementing (as I expect it will turn out a bit messy).

CFApproximantsIter::operator++() should be made more efficient.