Program to decompose a natural number N, up to u128::MAX, into a product of its prime factors. Based on the fundamental theorem of arithmetic every natural number larger than one is either a prime itself or can be represented as a product of primes that is unique up to the order of these prime numbers.
The whole factorization algorithm consists of trial division with the first one-thousand primes, Fermat's factorization and Lenstra elliptic-curve factorization using projective coordinates with Suyama's parametrization. After Fermat's and before elliptic-curve factorization step, possible primality of the number is checked and this is conducted either with Miller-Rabin or strong Baillie-PSW primality test depending on the magnitude of the number. Latter test is not deterministic in the number range it's used here (up to 128 bits) but there aren't known counterexamples.
To install as a dependency (library target) for some other program, add the following to your Cargo.toml
toml
[dependencies]
prime_factorization = "1.0.2"
For the binary target, run command cargo install prime_factorization and make sure that the installation location is in PATH (Rust toolchain properly configured).
Use the library as follows
```rust use prime_factorization::Factorization;
// Factorize following semiprime let num: u128 = 3746238285234848709_827;
let factor_repr = Factorization::run(num);
// Check that the returned factors are correct asserteq!(factorrepr.factors, vec![103979, 36028797018963913]); ```
Notice that all integers from 2 to 2^128 - 1 can be factorized but the used integer type must implement (alongside few others) trait From\
Sometimes it might be enough to check whether a particular number is a prime
```rust use prime_factorization::Factorization;
let num: u128 = 332306998946228968225951765070086_139;
// Use the is_prime convenience field
asserteq!(Factorization::run(num).isprime, true);
```
If the binary target was installed, CLI can be used as follows
bash
prime_factorization num [-p | --pretty]
where argument num is the mandatory natural number and option -p or --pretty is a print flag which, when given, causes the output to be in the proper factor representation format $$p1^{k1} * ... * pm^{km}$$ Without the flag, output only lists all the prime factors from the smallest to largest.
Elliptic-curve factorization must use few worker threads to be efficient. Default thread count is five which happened to be the most effective by rough empirical testing during the development period. Thread count can be changed by the MAX_WORKERS constant in the factor module but its value must be two at least (otherwise performance will deteriorate notably).
Miller-Rabin and Baillie-PSW primality tests are probabilistic but do not contain counterexamples in the number range this program uses. Elliptic-curve factorization uses random initial points on the curves which can cause some deviation to execution times.
This program is licensed under the CC0v1.