# 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

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

## Random number functions

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 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.

## Primality test predicates

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

## Linear algebra

The math module 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 math module provides the `Rvector` object which implements the real vector interface `Rvi`. Such interface provides numerous operators and methods for manipulating vectors as traditionnaly found in linear algebra packages.

## Standard vector operators

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

## Standard vector methods

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 math module provides the `Rmatrix` object which implements the real matrix interface `Rmi`. This interface is designed to operate with the vector interface and can handle sparse or full matrix.

## Standard matrix operators

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

## Standard matrix methods

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