Provided by: afnix_2.8.1-1_amd64 bug

NAME

       mth - standard math module

STANDARD MATH MODULE

       The  Standard  Mathematicalmodule  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
       The  mathmodule  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
       The  mathmodule  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-ppredicate.

       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-pand  miller-rabin-ppredicates  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-ppredicate  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-ppredicate 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-ppredicate  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-ppredicate 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-ppredicate takes care to run the optimal number of passes.

       General primality testing
       The  prime-probable-ppredicate  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

       Linear algebra
       The mathmodule provides an original and  extensive  support  for  linear  and  non  linear
       algebra.  This  includes  vector,  matrix  and  solvers.  Complex  methods  for non linear
       operations are also integrated tightly in this module.

       Real vector
       The mathmodule provides the Rvectorobject which implements the real vector interface  Rvi.
       Such  interface  provides  numerous  operators  and  methods  for  manipulating vectors as
       traditionnaly found in linear algebra packages.

       Operator   Description
       ==         compare two vectors for equality
       !=         compare two vectors for difference
       ?=         compare two vectors upto a precision
       +=         add a scalar or vector to the vector
       -=         substract a scalar or vector to the vector
       *=         multiply a scalar or vector to the vector
       /=         divide a vector by a scalar

       Method     Description
       set        set a vector component by index
       get        get a vector component  by index
       clear      clear a vector
       reset      reset a vector
       get-size   get the vector dimension
       dot        compute the dot product with another vector
       norm       compute the vector norm

       Creating a vector
       A vector is always created by size. A null size is  perfectly  valid.  When  a  vector  is
       created, it can be filled by setting the components by index.

       # create a simple vector
       const rv (afnix:mth:Rvector 3)
       # set the components by index
       rv:set 0 0.0
       rv:set 1 3.0
       rv:set 2 4.0

       Real matrix
       The  mathmodule provides the Rmatrixobject which implements the real matrix interface Rmi.
       This interface is designed to operate with the vector interface and can handle  sparse  or
       full matrix.

       Operator   Description
       ==         compare two matrices for equality
       !=         compare two matrices for difference
       ?=         compare two matrices upto a precision

       Method         Description

       set            set a matrix component by index
       get            get a matrix component  by index
       clear          clear a vector
       get-row-size   get the matrix row dimension
       get-col-size   get the matrix column dimension
       norm           compute the matrix norm

STANDARD MATH REFERENCE

       Rvi
       The  Rviclass an abstract class that models the behavior of a real based vector. The class
       defines the vector length as well as the accessor and mutator methods.

       Predicate

              rvi-p

       Inheritance

              Serial

       Operators

              == -> Boolean (Vector)
              The ==operator returns true if the calling object is equal to the vector argument.

              != -> Boolean (Vector)
              The ==operator returns true if the calling  object  is  not  equal  to  the  vector
              argument.

              ?= -> Boolean (Vector)
              The  ?=operator  returns true if the calling object is equal to the vector argument
              upto a certain precision.

              += -> Vector (Real|Vector)
              The +=operator returns the calling vector by adding the  argument  object.  In  the
              first  form,  the  real  argument  is added to all vector components. In the second
              form, the vector components are added one by one.

              -= -> Vector (Real|Vector)
              The -=operator returns the calling vector by substracting the argument  object.  In
              the  first  form, the real argument is substracted to all vector components. In the
              second form, the vector components are substracted one by one.

              *= -> Vector (Real|Vector)
              The *=operator returns the calling vector by multiplying the  argument  object.  In
              the  first  form,  the real argument is multiplied to all vector components. In the
              second form, the vector components are multiplied one by one.

              /= -> Vector (Real)
              The /=operator returns the calling vector by  dividing  the  argument  object.  The
              vector components are divided by the real argument.

       Methods

              set -> None (Integer Real)
              The setmethod sets a vector component by index.

              get -> Real (Integer)
              The getmethod gets a vector component by index.

              clear -> None (None)
              The clearmethod clears a vector. The dimension is not changed.

              reset -> None (None)
              The resetmethod resets a vector. The size is set to 0.

              get-size -> Real (None)
              The get-sizemethod returns the vector dimension.

              dot -> Real (Vector)
              The dotmethod computes the dot product with the vector argument.

              norm -> Real (None)
              The normmethod computes the vector norm.

              permutate -> Vector (Cpi)
              The   permutatemethod   permutates  the  vector  components  with  the  help  of  a
              combinatoric permutation object.

              reverse -> Vector (Cpi)
              The reversemethod reverse (permutate) the vector components  with  the  help  of  a
              combinatoric permutation object.

       Rvector
       The Rvectorclass is the default implementation of the real vector interface.

       Predicate

              r-vector-p

       Inheritance

              Rvi

       Constructors

              Rvector (None)
              The Rvectorconstructor creates a default null real vector.

              Rvector (Integer)
              The  Rvectorconstructor  creates  a  real  vector  those  dimension is given as the
              calling argument.

       Functions

              get-random-integer -> Integer (none|Integer)
              The get-random-integerfunction 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-realfunction 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-relatiffunction 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-primefunction  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-bitsetfunction returns a n bits random bitset. The argument  is  the
              number of bits.

              fermat-p -> Boolean (Integer|Relatif Integer|Relatif)
              The  fermat-ppredicate  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-ppredicate 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-ppredicate 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.