Module: Factorization

Factorization module for the UOR Math-JS library Contains algorithms for converting integers into their prime factorization (universal coordinates) Enhanced with Prime Framework optimizations for performance and efficiency

Source: Factorization.js, line 1

Members

(inner, constant) factorizationCache

Prime Framework-specific factorization optimizations and utilities Provides specialized methods for the Prime Framework

Source: Factorization.js, line 3223

Methods

(inner) ellipticCurveMethod(n, optionsopt) → {BigInt}

Lenstra's Elliptic Curve Method (ECM) for factorization Optimized for finding medium-sized factors of large numbers Enhanced with Prime Framework optimizations for universal coordinates

This implementation uses configurable parameters for number of curves, bounds, and memory limits. All limits can be set either through the options parameter or via the global configuration system in config.factorization.ecm.

Parameters:

Name Type Attributes Description

n

BigInt

The number to factor

options

Object

Algorithm options

Properties

Name	Type	Attributes	Description
`curves`	number	<optional>	Number of curves to try (default: config.factorization.ecm.maxCurves or scaled by number size)
`b1`	number	<optional>	Stage 1 bound (default: config.factorization.ecm.defaultB1)
`b2`	number	<optional>	Stage 2 bound (default: config.factorization.ecm.defaultB2 or b1*100 if 0)
`maxMemory`	number	<optional>	Max memory usage in MB (default: config.factorization.ecm.maxMemory or config.factorization.memoryLimit)

Source: Factorization.js, line 1540

Throws:

If input is not a positive composite number
Type PrimeMathError

Returns:

A non-trivial factor of n, or n if no factor is found

Type:: BigInt

(inner) factorArrayToMap(factorArray) → {Map.<BigInt, BigInt>}

Convert array of {prime, exponent} objects to factorization map

Parameters:

Name	Type	Description
`factorArray`	Array.<PrimeFactor>	Array of prime-exponent objects

Source: Factorization.js, line 3016

Returns:

Map of prime factors

Type:: Map.<BigInt, BigInt>

(inner) factorMapToArray(factorMap) → {Array.<PrimeFactor>}

Convert factorization map to array of {prime, exponent} objects

Parameters:

Name	Type	Description
`factorMap`	Map.<BigInt, BigInt>	Map of prime factors

Source: Factorization.js, line 3003

Returns:

Array of prime-exponent objects

Type:: Array.<PrimeFactor>

(inner) factorize(n) → {Map.<BigInt, BigInt>}

Factorize a number using trial division Implements Algorithm 1 from the specification for prime factorization

Parameters:

Name	Type	Description
`n`	number \| string \| BigInt	The number to factorize

Source: Factorization.js, line 616

Throws:

If n is not a positive integer
Type PrimeMathError

Returns:

A map where keys are prime factors and values are their exponents

Type:: Map.<BigInt, BigInt>

(inner) factorizeOptimal(n, optionsopt) → {Map.<BigInt, BigInt>}

Factorize a number using the most appropriate algorithm based on its size and properties Enhanced with Prime Framework optimizations for better performance and precision Implements the Prime Framework's requirements for unique factorization and canonical form Uses configurable thresholds from config.factorization.thresholds to dynamically select the most efficient factorization algorithm based on number characteristics

Parameters:

Name Type Attributes Description

n

number | string | BigInt

The number to factorize

options

Object

Factorization options

Properties

Name Type Attributes Default Description

advanced

boolean

false

Whether to use advanced factorization for large numbers

useCache

boolean

true

Whether to use factorization cache

parallelizeFactorization

boolean

false

Whether to use parallel factorization (when available)

algorithmParams

Object

Specific parameters for factorization algorithms

Properties

Name	Type	Attributes	Description
`ecmCurves`	number	<optional>	Number of curves for ECM
`ecmB1`	number	<optional>	B1 bound for ECM
`ecmB2`	number	<optional>	B2 bound for ECM (stage 2)
`qsFactorBase`	number	<optional>	Factor base size for quadratic sieve
`qsSieveSize`	number	<optional>	Sieve size for quadratic sieve

partialFactorization

boolean

false

Whether to allow partial factorization for very large numbers

validateFactors

boolean

true

Whether to validate that factors are indeed prime

Source: Factorization.js, line 2429

Throws:

If n is not a positive integer
Type PrimeMathError

Returns:

A map where keys are prime factors and values are their exponents

Type:: Map.<BigInt, BigInt>

(inner) factorizeParallel(n, optionsopt) → {Map.<BigInt, BigInt>}

Implements parallel factorization using worker threads when available Falls back to sequential factorization in environments without worker thread support

Parameters:

Name Type Attributes Description

n

number | string | BigInt

The number to factorize

options

Object

Factorization options

Properties

Name	Type	Attributes	Default	Description
`workerCount`	number	<optional>		Number of worker threads to use (default: CPU count - 1)
`useWorkStealing`	boolean	<optional>	true	Whether to use work stealing for load balancing

Source: Factorization.js, line 3074

Throws:

If n is not a positive integer
Type PrimeMathError

Returns:

A map where keys are prime factors and values are their exponents

Type:: Map.<BigInt, BigInt>

(inner) factorizePollardsRho(n, optionsopt) → {Map.<BigInt, BigInt>}

Factorize a large number using enhanced Pollard's Rho algorithm Improved with Prime Framework optimizations for performance

Parameters:

Name Type Attributes Description

n

number | string | BigInt

The number to factorize

options

Object

Factorization options

Properties

Name	Type	Attributes	Default	Description
`useCache`	boolean	<optional>	true	Whether to use factorization cache
`perfectFactorization`	boolean	<optional>	true	Whether to ensure complete factorization

Source: Factorization.js, line 2339

Throws:

If n is not a positive integer
Type PrimeMathError

Returns:

A map where keys are prime factors and values are their exponents

Type:: Map.<BigInt, BigInt>

(inner) factorizeWithPrimes(n) → {Map.<BigInt, BigInt>}

Factorize a number using optimized trial division with precomputed primes This is more efficient for moderately sized numbers

Parameters:

Name	Type	Description
`n`	number \| string \| BigInt	The number to factorize

Source: Factorization.js, line 671

Throws:

If n is not a positive integer
Type PrimeMathError

Returns:

A map where keys are prime factors and values are their exponents

Type:: Map.<BigInt, BigInt>

(inner) findFactorsPollardRho(n, factors, optionsopt) → {Map.<BigInt, BigInt>}

Recursively find factors using enhanced factorization algorithms Optimized with Prime Framework techniques for finding factors Implements a sophisticated approach that selects the most efficient algorithm for each phase of the factorization, following the Prime Framework requirements

Parameters:

Name	Type	Attributes	Description
`n`	BigInt		The number to factorize
`factors`	Map.<BigInt, BigInt>		The current factor map
`options`	Object	<optional>	Algorithm options

Source: Factorization.js, line 2135

Returns:

Updated factor map

Type:: Map.<BigInt, BigInt>

(inner) fromPrimeFactors(factors, optionsopt) → {BigInt}

Create a number from its prime factorization Implements the Prime Framework's universal coordinate system conversion

Parameters:

Name Type Attributes Description

factors

Array.<PrimeFactor> | Map.<BigInt, BigInt>

Array of {prime, exponent} objects or Map of prime->exponent

options

Object

Conversion options

Properties

Name	Type	Attributes	Default	Description
`validatePrimality`	boolean	<optional>	true	Whether to validate that each factor is prime
`enforceCanonicalForm`	boolean	<optional>	true	Whether to enforce canonical form (e.g., sort factors)

Source: Factorization.js, line 2870

Throws:

If any of the factors is not a prime number or has a non-positive exponent
Type PrimeMathError

Returns:

The number represented by the given prime factorization

Type:: BigInt

(inner) getErrorMessage(error) → {string}

Helper function to safely extract error message Non-recursive implementation to avoid stack overflows

Parameters:

Name	Type	Description
`error`	unknown	Any error value

Source: Factorization.js, line 27

Returns:

The error message

Type:: string

(inner) getPrimeFactors(n) → {Array.<BigInt>}

Get unique prime factors of a number (without exponents)

Parameters:

Name	Type	Description
`n`	number \| string \| BigInt	The number to get prime factors for

Source: Factorization.js, line 2992

Returns:

Array of prime factors (without repetition)

Type:: Array.<BigInt>

(inner) getPrimeSignature(n) → {BigInt}

Find the prime signature of a number (product of (p_i - 1)(p_i^e_i - 1)) Used in various number theory contexts

Parameters:

Name	Type	Description
`n`	number \| string \| BigInt	The number to find the signature for

Source: Factorization.js, line 3040

Returns:

The prime signature

Type:: BigInt

(inner) getRadical(n) → {BigInt}

Find the radical of a number (product of distinct prime factors)

Parameters:

Name	Type	Description
`n`	number \| string \| BigInt	The number to find the radical for

Source: Factorization.js, line 3028

Returns:

The radical of n

Type:: BigInt

(inner) isFactorizationComplete(factors, original) → {boolean}

Check if the factorization of a number is complete

Parameters:

Name	Type	Description
`factors`	Map.<BigInt, BigInt>	The factorization to check
`original`	BigInt	The original number

Source: Factorization.js, line 2836

Returns:

True if the factorization is complete, false otherwise

Type:: boolean

(inner) millerRabinTest(n, k) → {boolean}

Miller-Rabin primality test for larger numbers

Parameters:

Name	Type	Default	Description
`n`	BigInt		The number to test for primality
`k`	number	25	Number of iterations for accuracy (higher is more accurate)

Source: Factorization.js, line 740

Returns:

True if n is probably prime, false if definitely composite

Type:: boolean

(inner) modularFastExp(base, exponent, modulus) → {BigInt}

Fast modular exponentiation for Miller-Rabin test

Parameters:

Name	Type	Description
`base`	BigInt	Base value
`exponent`	BigInt	Exponent value
`modulus`	BigInt	Modulus for the operation

Source: Factorization.js, line 792

Returns:

Result of (base^exponent) % modulus

Type:: BigInt

(inner) pollardRho(n, optionsopt) → {BigInt}

Enhanced Pollard's Rho algorithm with cycle detection Optimized for the Prime Framework's factorization requirements

Parameters:

Name Type Attributes Description

n

BigInt

The number to factor

options

Object

Algorithm options

Properties

Name	Type	Attributes	Default	Description
`maxIterations`	number	<optional>		Maximum number of iterations (if not specified, no limit is applied)
`c`	BigInt	<optional>	1n	Polynomial constant
`timeLimit`	number	<optional>		Maximum time to spend in milliseconds (if not specified, no time limit is applied)

Source: Factorization.js, line 820

Returns:

A non-trivial factor of n, or n if no factor is found

Type:: BigInt

(inner) quadraticSieve(n, optionsopt) → {BigInt}

Quadratic Sieve implementation for factoring large numbers Implements a complete and efficient factorization algorithm aligned with the Prime Framework

Parameters:

Name Type Attributes Description

n

BigInt

The number to factor

options

Object

Algorithm options

Properties

Name	Type	Attributes	Default	Description
`factorBaseSize`	number	<optional>	100	Size of the factor base
`sieveSize`	number	<optional>	10000	Size of the sieve interval
`numRelations`	number	<optional>	0	Number of relations to collect (0 = auto)
`verbose`	boolean	<optional>	false	Whether to output debug info

Source: Factorization.js, line 904

Throws:

If input is not a positive composite number
Type PrimeMathError

Returns:

A non-trivial factor of n, or n if no factor is found

Type:: BigInt

Type Definitions

FactorizationResult

Type:

Object

Properties

Name	Type	Attributes	Description
`factors`	Map.<BigInt, BigInt>		Map of prime factors where key is the prime and value is the exponent
`isComplete`	boolean		Indicates if the factorization is complete (true) or partial (false)
`confidence`	number	<optional>	Confidence level for primality testing (0-1)

Source: Factorization.js, line 51

PrimeFactor

Type:

Object

Properties

Name	Type	Description
`prime`	BigInt	The prime number
`exponent`	BigInt	The exponent (power) of the prime

Source: Factorization.js, line 45

WorkerConfig

Type:

Object

Properties

Name	Type	Attributes	Description
`threadCount`	number	<optional>	Number of worker threads to use
`enableWorkStealing`	boolean	<optional>	Whether to enable work stealing
`chunkSize`	number	<optional>	Size of work chunks for distribution

Source: Factorization.js, line 58