org.soulspace.qclojure.domain.math — org.soulspace/qclojure 0.7.0

Mathematical operations and utilities for quantum algorithms.

complete-factorization clj

(complete-factorization factors)

Complete factorization of a vector of partial factors, e.g. [3 9].

Parameters:

• factors: Vector of factors to complete

Returns: Vector of complete factors, e.g. [3 3 3] for input [3 9].

complex-magnitude-squared clj

(complex-magnitude-squared z)

Calculate |z|² for a complex number represented as [real imag] or fastmath complex.

This function computes the squared magnitude of a complex number, which is useful for normalizing quantum states or measuring fidelity.

Parameters:

• z: A complex number in one of the following formats:
  • Fastmath complex number (e.g. (fc/complex 1 2))
  • Clojure vector [real imag]
  • Regular number (treated as real)

Returns: Squared magnitude as a number

complex? clj

(complex? z)

Check if value is a fastmath complex number (Vec2).

FastMath represents complex numbers as 2D vectors where the x component is the real part and the y component is the imaginary part.

Parameters:

• z: Value to test for complex number type

Returns: Boolean true if z is a fastmath Vec2 complex number, false otherwise

Example: (complex? (fc/complex 1 2)) ;=> true

(complex? 42) ;=> false

continued-fraction clj

(continued-fraction num den)

(continued-fraction num den max-depth)

(continued-fraction num den max-depth epsilon)

Convert a fraction to continued fraction representation.

This implementation handles numerical precision issues and early termination conditions that are important for Shor's algorithm. It can detect periodic patterns in the continued fraction expansion, which is crucial for finding the correct period.

Parameters:

• num: Numerator of the fraction
• den: Denominator of the fraction
• max-depth: (Optional) Maximum depth of continued fraction expansion
• epsilon: (Optional) Precision threshold for detecting near-zero remainders

Returns: Vector of continued fraction terms

convergents clj

(convergents cf)

Calculate convergents from continued fraction representation.

This enhanced implementation handles edge cases better and includes additional validation to ensure proper convergence, which is important for accurately extracting periods in Shor's algorithm.

Parameters:

• cf: Vector of continued fraction terms

Returns: Vector of convergents as [numerator denominator] pairs

find-period clj

(find-period measured-value precision N a)

Find the period from a phase estimate using improved continued fraction expansion.

This function implements a more robust version of period extraction from a phase measurement, which is critical for Shor's algorithm.

Parameters:

• measured-value: The value from quantum measurement
• precision: Number of bits used in phase estimation
• N: Modulus for period finding
• a: Base for modular exponentiation

Returns: Most likely period or nil if no valid period found

gcd clj

(gcd a b)

Calculate greatest common divisor using Euclidean algorithm.

This function computes the GCD of two integers using the efficient Euclidean algorithm, which is based on the principle that GCD(a, b) = GCD(b, a mod b).

Parameters:

• a: First integer
• b: Second integer

Returns: The greatest common divisor of a and b

lu-decomposition clj

(lu-decomposition matrix)

Perform LU decomposition with partial pivoting for matrix inversion. Returns [L U P] where P is the permutation matrix.

This function uses Gaussian elimination with partial pivoting to decompose the matrix.

Parameters:

• matrix: A square matrix to decompose (n×n)

Returns: A vector [L U P] where:

• L is the lower triangular matrix
• U is the upper triangular matrix
• P is the permutation vector (indices of rows after pivoting)

Example: (lu-decomposition [[4 3 2] [2 1 1] [1 1 1]]) ;=> [[[1.0 0.0 0.0] [0.5 1.0 0.0] [0.25 0.5 1.0]] [[4.0 3.0 2.0] [0.0 -0.5 -0.5] [0.0 0.0 0.0]] [0 1 2]] ; Permutation

max-coeff-magnitude-squared clj

(max-coeff-magnitude-squared matrix)

Get the maximum coefficient magnitude squared from a matrix.

This function computes the maximum of the squared magnitudes of complex coefficients in a matrix, which is useful for normalizing quantum states or measuring fidelity.

Parameters:

• matrix: A 2D vector of complex numbers (e.g. [[c11 c12] [c21 c22] ...])

Returns: Maximum coefficient magnitude squared as a number

mod-exp clj

(mod-exp base exp m)

Calculate (base^exp) mod m efficiently using binary exponentiation.

This function computes the modular exponentiation using the method of exponentiation by squaring, which is efficient for large numbers. It handles negative exponents by returning the modular inverse if needed.

Parameters:

• base: Base number
• exp: Exponent (can be negative)
• m: Modulus (must be positive)

Returns: The result of (base^exp) mod m

perfect-power-factor clj

(perfect-power-factor N)

Check if N is a perfect power and return its base factor.

A perfect power is a number that can be expressed as a^k for some integers a and k where k > 1. This function finds the smallest base a such that N = a^k for some k > 1.

This is used in Shor's algorithm for classical preprocessing - if N is a perfect power, we can factor it classically without needing quantum period finding.

Examples:

• perfect-power-factor(8) = 2 (since 8 = 2^3)
• perfect-power-factor(9) = 3 (since 9 = 3^2)
• perfect-power-factor(15) = 1 (since 15 is not a perfect power)

Parameters:

• N: The number to check for perfect power

Returns: Base factor a if N = a^k for some k > 1, otherwise returns 1

prime? clj

(prime? n)

Simple primality test for small numbers.

This function checks if a number is prime by testing divisibility against all integers from 2 to the square root of the number. It is not optimized for large numbers, but works well for small inputs.

Parameters:

• n: The number to check for primality

Returns: true if n is prime, false otherwise

round-precision clj

(round-precision x precision)

Round a number to specified decimal places.

Parameters:

• x: Number to round
• precision: Number of decimal places

Returns: Number rounded to specified precision

solve-linear-system clj

(solve-linear-system matrix b)

Solve Ax = b using LU decomposition with partial pivoting.

This function solves the linear system Ax = b where A is a square matrix and b is a vector. It uses LU decomposition with partial pivoting to efficiently solve the system.

Parameters:

• matrix: Square matrix A (n×n)
• b: Vector b (n×1)

Returns: Vector x (n×1) that satisfies Ax = b, or nil if no solution

Example: (solve-linear-system [[4 3 2] [2 1 1] [1 1 1]] [1 2 3]) ;=> [0.0 1.0 1.0] ; Solution to the system

tensor-product clj

(tensor-product matrix-a matrix-b)

Compute the tensor product of two matrices.

For matrices A (m×n) and B (p×q), returns the Kronecker product A⊗B (mp×nq).

Parameters:

• matrix-a: First matrix (m×n)
• matrix-b: Second matrix (p×q)

Returns: A new matrix representing the tensor product (mp×nq).