Conversion module for the UOR Math-JS library Provides utilities for converting between different number representations Supports full interoperability between standard JavaScript number types and UniversalNumber Implements the conversion utilities specified in the Prime Framework
- Source
Members
(inner, constant) Conversion
Combine all conversion utilities into a single module
- Source
(inner, constant) canonicalFrame
Default canonical reference frame used for standard computations In the Prime Framework, this represents the fixed reference point x ∈ M
- Source
Methods
(inner) baseConversionStep(toBase, optionsopt) → {ConversionStep}
Common conversion step: base conversion
Name | Type | Attributes | Description |
---|---|---|---|
toBase | number | Target base for conversion | |
options | Object | <optional> | Additional options |
- Source
A conversion step for the pipeline
- Type:
- ConversionStep
(inner) calculateGCD(a, b) → {BigInt}
Calculate the greatest common divisor (GCD) for fraction simplification
Name | Type | Description |
---|---|---|
a | BigInt | First number |
b | BigInt | Second number |
- Source
The GCD
- Type:
- BigInt
(inner) coherenceInnerProduct(a, b, optionsopt) → {BigInt}
Compute the coherence inner product between two universal coordinate representations This function implements the positive-definite inner product ⟨·,·⟩c defined in the Prime Framework
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
a | Map.<BigInt, BigInt> | | First universal coordinates | |||||||||||
b | Map.<BigInt, BigInt> | | Second universal coordinates | |||||||||||
options | Object | <optional> | Options for computing the inner product Properties
|
- Source
The coherence inner product value
- Type:
- BigInt
(inner) coherenceNorm(coordinates, optionsopt) → {BigInt}
Compute the coherence norm of universal coordinates This implements the norm derived from the coherence inner product
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
coordinates | Map.<BigInt, BigInt> | | Universal coordinates | |||||||||||
options | Object | <optional> | Options for computing the norm Properties
|
- Source
The coherence norm value
- Type:
- BigInt
(inner) computeDigitsFromFactorization(factorization, base) → {string|null}
Compute digits directly from prime factorization for certain bases This is faster than going through BigInt for some special cases
Name | Type | Description |
---|---|---|
factorization | Map.<BigInt, BigInt> | The prime factorization |
base | number | The target base |
- Source
The digits in the target base, or null if direct computation not possible
- Type:
- string |
null
(inner) convertBase(value, fromBaseopt, toBaseopt) → {string}
Convert a number from one base to another
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
value | string | | The value to convert | ||
fromBase | number | <optional> | 10 | The base of the input (default is decimal) |
toBase | number | <optional> | 10 | The base to convert to (default is decimal) |
- Source
If the value cannot be converted or the base is invalid
- Type
- PrimeMathError
The converted value as a string
- Type:
- string
(inner) convertBaseViaUniversal(value, fromBase, toBase, optionsopt) → {string}
Optimized direct base conversion utility Converts a number between different bases using universal coordinates Implements efficient algorithms that leverage prime factorization properties
Name | Type | Attributes | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
value | number | | The value to convert | ||||||||||||||||
fromBase | number | Base of the input (2-36) | ||||||||||||||||
toBase | number | Base for the output (2-36) | ||||||||||||||||
options | Object | <optional> | Additional options for the conversion Properties
|
- Source
The value in the target base
- Type:
- string
(inner) convertBigIntToBase(value, base) → {string}
Convert a BigInt to a string representation in the given base
Name | Type | Description |
---|---|---|
value | BigInt | The BigInt value to convert |
base | number | The base to convert to (2-36) |
- Source
The string representation in the given base
- Type:
- string
(inner) convertToUniversalStep(optionsopt) → {ConversionStep}
Common conversion step: convert to universal coordinates
Name | Type | Attributes | Description |
---|---|---|---|
options | Object | <optional> | Step-specific options |
- Source
A conversion step for the pipeline
- Type:
- ConversionStep
(inner) createConversionPipeline(steps, optionsopt) → {function}
Creates a conversion pipeline for processing large sets of numbers This allows efficient batch processing with minimal intermediate transformations
Name | Type | Attributes | Description |
---|---|---|---|
steps | Array.<ConversionStep> | Array of conversion steps to apply | |
options | ConversionPipelineOptions | <optional> | Pipeline configuration options |
- Source
Pipeline function
- Type:
- function
(inner) createReferenceFrame(options) → {ReferenceFrame}
Create a new reference frame for the Prime Framework Each reference frame corresponds to a fiber in the Prime Framework's algebraic geometry
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options | Object | Options for creating the reference frame Properties
|
- Source
A new reference frame object
- Type:
- ReferenceFrame
(inner) factorizationToBaseString(factorization, baseopt) → {string}
Convert a prime factorization to a string representation in the given base
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
factorization | Map.<BigInt, BigInt> | The prime factorization to convert | ||
base | number | <optional> | 10 | The base for the output representation (2-36) |
- Source
If the factorization is invalid or the base is not supported
- Type
- PrimeMathError
The string representation in the specified base
- Type:
- string
(inner) factorizationToBigInt(factorization) → {BigInt}
Convert a prime factorization to a BigInt value This is a standalone version of the method for converting a factorization to its numeric value
Name | Type | Description |
---|---|---|
factorization | Map.<BigInt, BigInt> | The prime factorization to convert |
- Source
If the factorization is invalid
- Type
- PrimeMathError
The numeric value represented by the factorization
- Type:
- BigInt
(inner) factorizationToString(factorsInput) → {string}
Create a string representation of a prime factorization
Name | Type | Description |
---|---|---|
factorsInput | Map.<BigInt, BigInt> | | Map of prime factors or object with factorization and sign |
- Source
Human-readable representation of the factorization (with optional negative sign)
- Type:
- string
(inner) fromBigInt(b) → {Map.<BigInt, BigInt>}
Convert a BigInt to a factorized universal representation
Name | Type | Description |
---|---|---|
b | BigInt | The BigInt value to convert |
- Source
The prime factorization (universal coordinates)
- Type:
- Map.<BigInt, BigInt>
(inner) fromNumber(n) → {Object}
Convert a JavaScript Number to a factorized universal representation Floors the number if it's not an integer, throws an error if not safe (above 2^53)
Name | Type | Description |
---|---|---|
n | number | The JavaScript Number to convert |
- Source
If the number is not safe or is not finite
- Type
- PrimeMathError
The prime factorization (universal coordinates) and sign flag
- Type:
- Object
(inner) fromString(str, baseopt) → {Object}
Parse a string representing a number in a given base and convert to universal coordinates
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
str | string | The string representing a number | ||
base | number | <optional> | 10 | The base of the input string (configurable, default: 2-36) |
- Source
If the string cannot be parsed or is zero
- Type
- PrimeMathError
The prime factorization (universal coordinates) and sign flag
- Type:
- Object
(inner) getCliffAlgebra() → {Object}
Get the Clifford algebra at this reference point In the Prime Framework, the fiber at each point is modeled as a Clifford algebra Cx
- Source
The Clifford algebra object
- Type:
- Object
(inner) getDigitCharset(base) → {string}
Get the digit character set for a specific base Supports extended bases beyond the standard 36
Name | Type | Description |
---|---|---|
base | number | The base for which to get the character set |
- Source
The character set for the given base
- Type:
- string
(inner) getDigits(value, baseopt, leastSignificantFirstopt) → {Array.<number>}
Extract the digits of a number in a specific base
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
value | number | | The value to extract digits from | ||
base | number | <optional> | 10 | The base to use for extraction (default is decimal) |
leastSignificantFirst | boolean | <optional> | false | If true, returns digits with least significant first |
- Source
If the value is invalid or the base is not supported
- Type
- PrimeMathError
Array of digits in the specified base
- Type:
- Array.<number>
(inner) getErrorMessage(error) → {string}
Helper function to safely extract error message Non-recursive implementation to avoid stack overflows
Name | Type | Description |
---|---|---|
error | unknown | Any error value |
- Source
The error message
- Type:
- string
(inner) isCanonicalForm(coordinates, optionsopt) → {boolean}
Check if universal coordinates are in canonical (minimal norm) form This implements the coherence criteria from the Prime Framework specification as detailed in lib-spec.md section "Coherence Inner Product and Norm"
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
coordinates | Map.<BigInt, BigInt> | | Universal coordinates | |||||||||||
options | Object | <optional> | Options for checking canonical form Properties
|
- Source
Whether the coordinates are in canonical form
- Type:
- boolean
(inner) isPrime(value) → {boolean}
Determines if a given number is a valid prime This ensures the factorization contains only actual primes as required by the Prime Framework
Name | Type | Description |
---|---|---|
value | BigInt | The value to check for primality |
- Source
Whether the value is prime
- Type:
- boolean
(inner) parseFactorization(str, optionsopt) → {Map.<BigInt, BigInt>|Object}
Parses a string representation of a prime factorization Accepts formats like "2^3 × 3^2 × 5", "2^3 * 3^2 * 5", "22233*5", a single term like "2^4" Also handles negative representations like "-(2^3 × 3)" or "-1"
Name | Type | Attributes | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
str | string | The string representation of the factorization | |||||||||||
options | Object | <optional> | Optional parameters for parsing Properties
|
- Source
If the string is not a valid factorization
- Type
- PrimeMathError
Map of prime factors (or with sign flag if requested)
- Type:
- Map.<BigInt, BigInt> |
Object
(inner) toFraction(value) → {Object}
Convert a number, string, or BigInt to a fraction (numerator/denominator) This is useful for exact representation of decimal values
Name | Type | Description |
---|---|---|
value | string | | The value to convert (eg. "3.14159", 3.14159, or BigInt) |
- Source
If the value is not a valid number
- Type
- PrimeMathError
Object with numerator and denominator as BigInt values
- Type:
- Object
(inner) toJSON(data, optionsopt) → {string}
Serializes number data to JSON format with advanced options
Name | Type | Attributes | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
data | Object | The number data to serialize Properties
| ||||||||||||||||
options | Object | <optional> | Serialization options Properties
|
- Source
JSON string representation
- Type:
- string
(inner) toScientificNotation(value, precisionopt) → {string}
Convert a number to a string representation in scientific notation
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
value | number | | The value to convert | ||
precision | number | <optional> | 6 | Number of significant digits to include |
- Source
If the value is invalid
- Type
- PrimeMathError
The number in scientific notation
- Type:
- string
(inner) transform(coordinates, _targetFrame) → {Map.<BigInt, BigInt>|Object}
Transform coordinates from this frame to another This implements the G-action on M that carries representations between fibers As described in lib-spec.md's section on Topological and Geometric Framework
Name | Type | Description |
---|---|---|
coordinates | Map.<BigInt, BigInt> | | Universal coordinates to transform |
_targetFrame | ReferenceFrame | The target reference frame (used for conforming to abstract interface) |
- Source
Transformed coordinates
- Type:
- Map.<BigInt, BigInt> |
Object
(inner) tryBaseConversionShortcut(value, fromBase, toBase) → {string|null}
Try optimized base conversion shortcuts for common bases Provides fast conversion paths for common base combinations like binary ↔ hexadecimal
Name | Type | Description |
---|---|---|
value | string | | The value to convert |
fromBase | number | The base of the input |
toBase | number | The base to convert to |
- Source
The converted value or null if no shortcut is available
- Type:
- string |
null
(inner) validateStringForBase(str, base) → {boolean}
Validates if a string is a valid representation of a number in the given base
Name | Type | Description |
---|---|---|
str | string | The string to validate |
base | number | The base of the number representation (configurable, default: 2-36) |
- Source
True if the string is a valid representation
- Type:
- boolean
Type Definitions
BigIntResult
- Object
Name | Type | Attributes | Description |
---|---|---|---|
format | string | The format used (standard, compact, binary, streaming) | |
primeCount | number | Number of prime factors | |
timestamp | string | ISO timestamp of serialization | |
type | string | Always 'Factorization' | |
factors | Record.<string, string> | Object mapping prime factors to exponents | |
metadata | FactorizationMetadata | <optional> | Optional metadata |
type | string | Always 'CompactFactorization' | |
primes | Array.<string> | Array of prime factors as strings | |
exponents | Array.<string> | Array of exponents as strings | |
metadata | FactorizationMetadata | <optional> | Optional metadata |
type | string | Always 'BinaryFactorization' | |
encoding | string | Encoding type (e.g., 'base64') | |
data | string | Encoded data | |
metadata | FactorizationMetadata | <optional> | Optional metadata |
type | string | Always 'StreamingFactorization' | |
chunkCount | number | Number of chunks | |
chunks | Array.<{primes: Array.<string>, exponents: Array.<string>}> | Array of chunks | |
metadata | FactorizationMetadata | <optional> | Optional metadata |
type | string | Always 'BigInt' | |
value | string | String representation of the BigInt value | |
metadata | Object | <optional> | Optional metadata |
- Source
ConversionPipelineOptions
Conversion pipeline configuration options
- Object
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
parallel | boolean | <optional> | false | Whether to process items in parallel (when supported) |
batchSize | number | <optional> | 100 | Size of batches for batch processing |
preserveFactorization | boolean | <optional> | true | Whether to preserve factorization between steps |
streamingOutput | boolean | <optional> | false | Whether to stream output or return all at once |
- Source
ConversionStep
Conversion pipeline step definition
- Object
Name | Type | Attributes | Description |
---|---|---|---|
type | string | Type of conversion step ('format', 'transform', 'compute') | |
process | function | Function to process a value in the pipeline | |
options | Object | <optional> | Step-specific options |
- Source
DigitResult
Get the digit representation of a number in a specific base This extracts digits directly from the value
- Object
Name | Type | Attributes | Description |
---|---|---|---|
digits | Array.<number> | Array of digits in the specified base | |
isNegative | boolean | <optional> | Whether the value is negative (only included if includeSign is true) |
- Source
ParsedJSONResult
Parses a JSON string back to number data with advanced options
- Object
Name | Type | Attributes | Description |
---|---|---|---|
value | BigInt | | The numeric value or prime factorization | |
isFactorization | boolean | Whether the value is a factorization (true) or BigInt (false) | |
metadata | Object | <optional> | Additional metadata if present and validated |
- Source
ReferenceFrame
Represents a reference frame in the Prime Framework A reference frame defines a specific algebraic context for universal coordinates This corresponds to a point on the smooth reference manifold M described in lib-spec.md
- Object
Name | Type | Description |
---|---|---|
id | string | Unique identifier for the reference frame |
parameters | Map.<string, any> | Parameters defining the specific reference geometry |
transform | function | Function to transform coordinates between frames |
getCliffAlgebra | function | Gets the Clifford algebra at this reference point |
- Source
SerializationFormat
Advanced serialization format options Provides different serialization strategies for universal coordinates
- 'standard' |
'compact' | 'binary' | 'streaming'
- Source