Provided by: afnix_2.2.0-2ubuntu1_amd64 bug

NAME

       mth - standard math module

STANDARD MATH MODULE

       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

STANDARD MATH REFERENCE

       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.