org.soulspace.qclojure.domain.math.core — org.soulspace/qclojure 0.11.1

Facade for linear algebra operations with pluggable backends.

Goals:

• Provide a single, meaningful API for matrix and vector operations.
• Allow swapping implementations (pure Clojure Math, Fastmath, Neanderthal) without changing call sites.
• Keep data shapes simple: matrices as vectors of row vectors; vectors as vectors of numbers.
• Handle conversions between FastMath Vec2 format and backend-specific representations.

Default backend: :pure, implemented via org.soulspace.qclojure.domain.math.clojure-math.

Use set-backend! to change the global backend, or with-backend to override in a dynamic scope.

*backend* clj

Current math backend instance. Bind dynamically with with-backend. Defaults to a FastMathComplexBackend instance.

*backend-key* clj

Current math backend key for informational purposes.

*tolerance* clj

add clj

(add A B)

Perform matrix addition A + B.

Parameters:

• A: First matrix
• B: Second matrix with same dimensions as A

Returns: Matrix representing A + B

available-backends clj

(available-backends)

Return the set of available backend keys.

Returns: Set of backend keywords that can be used with set-backend! or create-backend

cholesky-decomposition clj

(cholesky-decomposition A)

Compute the Cholesky decomposition A = L L†.

Parameters:

• A: Positive semidefinite matrix

Returns: Map containing:

• :L - Lower triangular matrix such that A = L L†

Note: May throw or return nil if A is not positive semidefinite

complex-matrix clj

(complex-matrix real-m imag-m)

Create a complex matrix from real & imaginary part matrices.

Parameters:

• real-m: matrix (vector of row vectors) of real parts
• imag-m: matrix of imaginary parts (same shape)

Returns complex matrix as Vec2 format [[#vec2 [...], ...], ...].

complex-vector clj

(complex-vector real-part imag-part)

Create a complex vector from parallel real and imaginary part collections.

Parameters:

• real-part: sequence of real components
• imag-part: sequence of imaginary components (same length)

Returns: Complex vector as Vec2 format [#vec2 [...], #vec2 [...], ...].

Example: (complex-vector [1 0] [0 1]) ; => [#vec2 [1.0, 0.0], #vec2 [0.0, 1.0]]

condition-number clj

(condition-number A)

Compute the 2-norm condition number κ₂(A) = σ_max / σ_min.

Parameters:

• A: Square matrix

Returns: Positive real number representing the condition number

Note: Higher values indicate numerical instability in linear solves

conjugate-transpose clj

(conjugate-transpose A)

Compute the conjugate transpose Aᴴ (Hermitian adjoint).

Parameters:

• A: Matrix

Returns: Matrix representing the conjugate transpose of A

Note: For real matrices, this is equivalent to transpose

create-backend clj

(create-backend backend-key)

(create-backend backend-key opts)

Create a backend instance for the given key and optional configuration.

Parameters:

• backend-key: Keyword identifying the backend type (from available-backends)
• opts: Optional map of backend-specific configuration options

Returns: Backend instance implementing the mathematical operation protocols

current-tolerance clj

(current-tolerance)

Return the effective tolerance used for approximate numeric comparisons.

This reads the dynamic var tolerance. Backend specific overrides (if any) should bind tolerance when performing computations so tests and client code can query a single source of truth.

Returns: Current tolerance value as a double

eigen-general clj

(eigen-general A)

Compute eigenvalues for a general (possibly non-Hermitian) matrix.

Parameters:

• A: Square matrix

Returns: Map containing:

• :eigenvalues - Vector of eigenvalue approximations
• :iterations - Number of iterations used in computation

eigen-hermitian clj

(eigen-hermitian A)

Compute the eigendecomposition of a Hermitian matrix.

Parameters:

• A: Square Hermitian matrix

Returns: Map containing:

• :eigenvalues - Vector of eigenvalues in ascending order
• :eigenvectors - Vector of corresponding eigenvector columns [v0 v1 ...] (Both eigenvalues and eigenvectors returned in original format)

get-backend clj

(get-backend)

Return the current backend key.

Returns: Keyword identifying the currently active backend

get-backend-instance clj

(get-backend-instance)

Return the current backend instance implementing the real/complex protocols.

Returns: Backend instance that implements the mathematical operation protocols

hadamard-product clj

(hadamard-product A B)

Compute the element-wise (Hadamard) product A ⊙ B.

Parameters:

• A: First matrix
• B: Second matrix with same dimensions as A

Returns: Matrix with element-wise multiplication of A and B

hermitian? clj

(hermitian? A)

(hermitian? A eps)

Test if a matrix is Hermitian (A ≈ Aᴴ).

Parameters:

• A: Square matrix
• eps: Optional tolerance for approximate equality (uses current tolerance if not provided)

Returns: Boolean indicating whether A is Hermitian or real symmetric

inner-product clj

(inner-product x y)

Compute the vector inner product ⟨x|y⟩.

Parameters:

• x: First vector
• y: Second vector with same length as x

Returns: Scalar representing the inner product

Note: For complex vectors, computes ⟨x|y⟩ = Σ xᵢ* yᵢ (conjugate x)

kronecker-product clj

(kronecker-product A B)

Compute the Kronecker (tensor) product A ⊗ B.

Parameters:

• A: First matrix
• B: Second matrix

Returns: Matrix representing the Kronecker product A ⊗ B

Note: Essential for quantum computing multi-qubit operations

lu-decomposition clj

(lu-decomposition A)

Compute the LU decomposition A = P L U.

Parameters:

• A: Square matrix

Returns: Map containing:

• :P - Row permutation matrix
• :L - Lower triangular matrix
• :U - Upper triangular matrix

matrix-exp clj

(matrix-exp A)

Compute the matrix exponential exp(A).

Parameters:

• A: Square matrix

Returns: Matrix representing exp(A)

Note: Important for quantum time evolution operators

matrix-from-eigen clj

(matrix-from-eigen eigenvalues eigenvectors)

Reconstruct (approximate) Hermitian matrix from eigenvalues & eigenvectors.

Parameters:

• eigenvalues vector [λ₀ … λₙ₋₁]
• eigenvectors vector of eigenvector column vectors [v₀ …]

Returns: Matrix Σ λᵢ vᵢ vᵢᵀ (real case only for now) in Vec2 format. NOTE: Complex support can be added when complex eigenvectors are exposed.

matrix-inverse clj

(matrix-inverse A)

Compute the matrix inverse A⁻¹.

Parameters:

• A: Square matrix

Returns: Inverse matrix A⁻¹

Throws: Exception if matrix is singular

matrix-log clj

(matrix-log A)

Compute the principal matrix logarithm log(A).

Parameters:

• A: Square matrix

Returns: Matrix representing the principal branch of log(A)

matrix-multiply clj

(matrix-multiply A B)

Perform matrix multiplication A × B.

Parameters:

• A: Left matrix
• B: Right matrix with compatible dimensions

Returns: Matrix representing the product A × B

matrix-sqrt clj

(matrix-sqrt A)

Compute the principal matrix square root √A.

Parameters:

• A: Square matrix

Returns: Matrix representing the principal square root of A

matrix-vector-product clj

(matrix-vector-product A x)

Perform matrix–vector multiplication A × x.

Parameters:

• A: Matrix
• x: Vector with compatible dimensions

Returns: Vector representing the product A × x

negate clj

(negate A)

Compute the additive inverse -A.

Parameters:

• A: Matrix

Returns: Matrix representing -A

norm2 clj

(norm2 x)

Compute the Euclidean norm ||x||₂.

Parameters:

• x: Vector

Returns: Non-negative real number representing the Euclidean norm

outer-product clj

(outer-product x y)

Compute the outer product x ⊗ y†.

Parameters:

• x: First vector
• y: Second vector

Returns: Matrix representing the outer product x ⊗ y† in Vec2 format (no conjugation of x)

Note: For quantum states, this creates projector-like matrices

positive-semidefinite? clj

(positive-semidefinite? A)

Test if a matrix is positive semidefinite.

Parameters:

• A: Square Hermitian matrix

Returns: Boolean indicating whether all eigenvalues of A are ≥ -eps

Note: Matrix must be Hermitian for meaningful results

qr-decomposition clj

(qr-decomposition A)

Compute the QR decomposition A = Q R.

Parameters:

• A: Matrix

Returns: Map containing:

• :Q - Orthogonal/unitary matrix
• :R - Upper triangular matrix

scale clj

(scale A alpha)

Perform scalar multiplication α · A.

Parameters:

• A: Matrix
• alpha: Scalar value

Returns: Matrix representing α · A

set-backend! clj

(set-backend! backend-key)

Set the global backend by key.

Parameters:

• backend-key: Keyword identifying the backend (use keys from available-backends)

Returns: The backend key that was set

Note: Prefer with-backend for scoped overrides instead of global mutation

shape clj

(shape A)

Return the shape of a matrix.

Parameters:

• A: Matrix

Returns: Vector [rows cols] indicating the matrix dimensions

solve-linear-system clj

(solve-linear-system A b)

Solve the linear system Ax = b.

Parameters:

• A: Matrix (square)
• b: Vector or matrix

Returns: Solution vector(s) x such that Ax = b

spectral-norm clj

(spectral-norm A)

Compute the spectral norm ||A||₂ (largest singular value).

Parameters:

• A: Matrix

Returns: Non-negative real number representing the largest singular value

subtract clj

(subtract A B)

Perform matrix subtraction A - B.

Parameters:

• A: First matrix
• B: Second matrix with same dimensions as A

Returns: Matrix representing A - B

svd clj

(svd A)

Compute the Singular Value Decomposition of a matrix.

Parameters:

• A: Matrix

Returns: Map containing:

• :U - Left singular vectors matrix
• :singular-values - Vector of singular values [σ0≥σ1≥...] in descending order
• :Vt - Right singular vectors transpose matrix

Note: Renames backend keys (:S :V†) for consistency

trace clj

(trace A)

Compute the trace Tr(A) = Σ aᵢᵢ.

Parameters:

• A: Square matrix

Returns: Scalar representing the sum of diagonal elements

transpose clj

(transpose A)

Compute the transpose Aᵀ.

Parameters:

• A: Matrix

Returns: Matrix representing the transpose of A

unitary? clj

(unitary? U)

(unitary? U eps)

Test if a matrix is unitary (Uᴴ U ≈ I).

Parameters:

• U: Square matrix
• eps: Optional tolerance for approximate equality (uses current tolerance if not provided)

Returns: Boolean indicating whether U is unitary (or orthogonal for real matrices)

with-backend clj macro

(with-backend backend & body)

Evaluate body with the backend temporarily bound to the specified backend.

Parameters:

• backend: Either a backend keyword or a backend instance
• body: Forms to evaluate with the temporary backend binding

Returns: Result of evaluating body with the temporary backend