# FreeBSD Manual Pages

```mth(3)				 AFNIX Module				mth(3)

NAME
mth - standard math module

STANDARD MATH MODULE
The  Standard Mathematicalmodule	is an original implementation of vari-
ous mathematical	facilities. The	module can  be	divided	 into  several
catgeories  which include convenient functions, linear algebra and real
analysis.

Random number services
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  ma-
chine to	another.

Primality testing services
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  em-
ployed, 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  computa-
tion.  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  num-
ber,  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 incorpo-
rates  various primality	tests. To make the story short,	the prime can-
didate 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-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 in-
cluded 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	proba-
ble 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 sec-
ond 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.

AFNIX				  2017-04-29				mth(3)
```

NAME | STANDARD MATH MODULE | STANDARD MATH REFERENCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=afnix::mth&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>