Provided by: afnix_2.2.0-2ubuntu1_amd64 NAME

```       mth - standard math module

```

STANDARDMATHMODULE

```       The  Standard  Mathematical  module  is an original implementation of various mathematical
facilities. The module can be divided into several  catgeories  which  include  convenient
functions, linear algebra and real analysis.

Random number services
The  math  module  provides  various  functions  that generate random numbers in different
formats.

Function             Description
get-random-integer   return a random integer number
get-random-real      return a random real number between 0.0 and 1.0
get-random-relatif   return a random relatif number
get-random-prime     return a random probable prime relatif number

The numbers are generated with the help of the system random generator. Such generator  is
machine dependant and results can vary from one machine to another.

Primality testing services
The  math module provides various predicates that test a number for a primality condition.
Most of these predicates are intricate  and  are  normally  not  used  except  the  prime-
probable-p predicate.

Predicate          Description
fermat-p           Fermat test predicate
miller-rabin-p     Miller-Rabin test predicate
prime-probable-p   general purpose prime probable test
get-random-prime   return a random probable prime relatif number

The  fermat-p  and  miller-rabin-p  predicates  return  true if the primality condition is
verified. These predicate operate with a base number. The prime  number  to  test  is  the
second argument.

Fermat primality testing
The  fermat-p predicate is a simple primality test based on the "little Fermat theorem". A
base number greater than 1 and less than the number to test must be given to run the test.

afnix:mth:fermat-p 2 7

In the preceeding example, the number 7 is tested,  and  the  fermat-p  predicate  returns
true.  If  a number is prime, it is guaranted to pass the test. The oppositte is not true.
For example, 561 is a composite number, but the Fermat test will succeed with the base  2.
Numbers  that  successfully  pass  the  Fermat  test  but  which  are composite are called
Carmichael numbers. For those numbers, a better test needs to be employed, such  like  the
Miller-Rabin test.

Miller-Rabin primality testing
The  miller-rabin-p  predicate  is  a  complex  primality  test  that is more efficient in
detecting prime number at the cost of a longer computation. A base number greater  than  1
and less than the number to test must be given to run the test.

afnix:mth:miller-rabin-p 2 561

In  the  preceeding  example, the number 561, which is a Carmichael number, is tested, and
the miller-rabin-p predicate returns false. The probability that a number is prime depends
on  the  number of times the test is ran. Numerous studies have been made to determine the
optimal number of passes that are needed to declare that a number is  prime  with  a  good
probability.  The  prime-probable-p  predicate  takes  care  to  run the optimal number of
passes.

General primality testing
The prime-probable-p predicate is a  complex  primality  test  that  incorporates  various
primality  tests.  To  make  the  story  short, the prime candidate is first tested with a
series of small prime numbers. Then a fast Fermat test is executed. Finally, a  series  of
Miller-Rabin tests are executed. Unlike the other primality tests, this predicate operates
with a number only and optionally, the number  of  test  passes.  This  predicate  is  the
recommended test for the folks who want to test their numbers.

afnix:mth:prime-probable-p 17863

```

STANDARDMATHREFERENCE

```       Functions

get-random-integer -> Integer (none|Integer)
The  get-random-integer function returns a random integer number. Without argument,
the integer range is machine dependent. With one integer  argument,  the  resulting
integer number is less than the specified maximum bound.

get-random-real -> Real (none|Boolean)
The  get-random-real  function returns a random real number between 0.0 and 1.0. In
the first form, without argument, the random number is between 0.0 and 1.0 with 1.0
included.  In  the second form, the boolean flag controls whether or not the 1.0 is
included in the result. If the argument is false, the 1.0 value is guaranted to  be
excluded  from  the  result.  If the argument is true, the 1.0 is a possible random
real value. Calling this function with the argument set to true  is  equivalent  to
the first form without argument.

get-random-relatif -> Relatif (Integer|Integer Boolean)
The get-random-relatif function returns a n bits random positive relatif number. In
the first form, the argument is the number of bits. In the second form,  the  first
argument  is  the  number of bits and the second argument, when true produce an odd
number, or an even number when false.

get-random-prime -> Relatif (Integer)
The get-random-prime function returns a n bits  random  positive  relatif  probable
prime  number. The argument is the number of bits. The prime number is generated by
using the Miller-Rabin primality test. As such, the  returned  number  is  declared
probable prime. The more bits needed, the longer it takes to generate such number.

get-random-bitset -> Bitset (Integer)
The  get-random-bitset function returns a n bits random bitset. The argument is the
number of bits.

fermat-p -> Boolean (Integer|Relatif Integer|Relatif)
The fermat-p predicate returns true if the little fermat theorem is validated.  The
first  argument  is  the base number and the second argument is the prime number to
validate.

miller-rabin-p -> Boolean (Integer|Relatif Integer|Relatif)
The miller-rabin-p predicate returns true if the Miller-Rabin  test  is  validated.
The  first  argument is the base number and the second argument is the prime number
to validate.

prime-probable-p -> Boolean (Integer|Relatif [Integer])
The prime-probable-p predicate returns true if the argument is a probable prime. In
the  first form, only an integer or relatif number is required. In the second form,
the number of iterations is specified as  the  second  argument.  By  default,  the
number of iterations is specified to 56.
```