mth(3)

🌸 mth(3) — standard math module 🌸

NAME

mth — standard math module 💖

---

STANDARD MATH MODULE

Okay bestie, listen up: the Standard Mathematical module is an original implementation of various mathematical facilities. It's giving convenient functions, linear algebra, and real analysis — the whole squad. 🫶

Random number

The math module provides various functions that generate random numbers in different formats. No cap, it's a whole vibe.

• 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. That generator is machine dependent, so results can vary from one machine to another. It's not a bug, it's a feature of the machine, iykyk.

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. So if you're not trying to be extra, just use that one, periodt.

• 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 predicates operate with a base number. The prime number to test is the second argument. Got it? 💅

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 preceding example, the number 7 is tested, and the fermat-p predicate returns true. If a number is prime, it is guaranteed to pass the test. The opposite 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. So don't get tricked, bestie. 😭

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 preceding 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 run. 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. So you don't have to do the math, it's already doing the most. 💅

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. It's the main character of primality testing, no cap. 👑

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. It's giving math girlie energy. 🌈

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 traditionally found in linear algebra packages.

Operators:

• == — 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

Methods:

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

Operators:

• == — compare two matrices for equality
• != — compare two matrices for difference
• ?= — compare two matrices upto a precision

Methods:

• 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

🦋 Rvi 🦋

okay so Rvi is an abstract class — it models the behavior of a real based vector. It's the blueprint, not the finished fit: it defines the vector length plus all the accessor and mutator methods. Think of it as the vibe, and Rvector as the outfit. ✨

💅 Predicate 💅

• rvi-p

🧬 Inheritance 🧬

• Serial

🔥 Operators 🔥

• == -> Boolean (Vector) — returns true if the calling object is equal to the vector argument. equality check, slay 💖
• != -> Boolean (Vector) — returns true if the calling object is not equal to the vector argument. (and yes, the original text literally says "The == operator" right here — copy-paste crime, we're leaving it, she's doing her best 🙈)
• ?= -> Boolean (Vector) — returns true if the calling object is equal to the vector argument up to a certain precision. floats, amirite 😭
• += -> Vector (Real|Vector) — returns the calling vector after adding the argument object. Form one: the real argument gets added to all vector components. Form two: the vector components get added one by one. 🫶
• -= -> Vector (Real|Vector) — returns the calling vector after subtracting the argument object. Form one: the real argument is subtracted from all vector components. Form two: the components are subtracted one by one.
• *= -> Vector (Real|Vector) — returns the calling vector after multiplying by the argument object. Form one: the real argument multiplies all vector components. Form two: the components multiply one by one.
• /= -> Vector (Real) — returns the calling vector after dividing by the argument object. The vector components get divided by the real argument. (only the real form, bestie — no vector-on-vector division here 💀)

🎀 Methods 🎀

• set -> None (Integer Real) — sets a vector component by index.
• get -> Real (Integer) — gets a vector component by index.
• clear -> None (None) — clears a vector. The dimension is not changed. 🌸
• reset -> None (None) — resets a vector. The size is set to 0. gone, reduced to atoms 💀
• get-size -> Real ( None) — returns the vector dimension.
• dot -> Real (Vector) — computes the dot product with the vector argument. math girlies rise 👑
• norm -> Real (None) — computes the vector norm.
• permutate -> Vector (Cpi) — permutates the vector components with the help of a combinatoric permutation object.
• reverse -> Vector (Cpi) — reverses (permutates) the vector components with the help of a combinatoric permutation object. ✨

---

🌈 Rvector 🌈

Rvector is the default implementation of the real vector interface. no cap, this is the one you'll actually be touching. 💜

💅 Predicate 💅

• r-vector-p

🧬 Inheritance 🧬

• Rvi

🍼 Constructors 🍼

• Rvector (None) — creates a default null real vector.
• Rvector (Integer) — creates a real vector whose dimension is given as the calling argument.

🌟 Functions 🌟

• get-random-integer -> Integer (none|Integer) — returns a random integer number. With no 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) — returns a random real number between 0.0 and 1.0. First form (no argument): the random number is between 0.0 and 1.0 with 1.0 included. Second form: the boolean flag controls whether or not 1.0 is included in the result. If the argument is false, the 1.0 value is guaranteed to be excluded from the result. If the argument is true, 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) — returns a n bits random positive relatif number. First form: the argument is the number of bits. Second form: the first argument is the number of bits, and the second argument produces an odd number when true, or an even number when false.
• get-random-prime -> Relatif (Integer) — returns a n bits random positive relatif probable prime number. The argument is the number of bits. The prime is generated using the Miller-Rabin primality test, so the returned number is declared probable prime. The more bits you need, the longer it takes to generate such a number. 💀 (be patient, queen)
• get-random-bitset -> Bitset (Integer) — returns a n bits random bitset. The argument is the number of bits.
• fermat-p -> Boolean (Integer|Relatif Integer|Relatif) — returns true if the little fermat theorem is validated. The first argument is the base number, the second argument is the prime number to validate.
• miller-rabin-p -> Boolean (Integer|Relatif Integer|Relatif) — returns true if the Miller-Rabin test is validated. The first argument is the base number, the second argument is the prime number to validate.
• prime-probable-p -> Boolean (Integer|Relatif [Integer]) — returns true if the argument is a probable prime. First form: just an integer or relatif number, that's it. Second form: the number of iterations is specified as the second argument. By default, the number of iterations is specified to 56. ✨

---

okay that's the whole vibe check, bestie 🎀 this page ships as part of the AFNIX Module documentation, under the AFNIX banner, and it lives in section mth(3) — go forth and vectorize responsibly, ily 💖🦋