Class AbstractNativeCPULinearAlgebraBackend<E>

java.lang.Object

org.episteme.nativ.mathematics.linearalgebra.backends.AbstractNativeCPULinearAlgebraBackend<E>

All Implemented Interfaces:

AutoCloseable, LinearAlgebraProvider<E>, AlgorithmProvider, Backend, ComputeBackend, CPUBackend, NativeBackend

Direct Known Subclasses:

NativeCPULinearAlgebraComplexBackend, NativeCPULinearAlgebraRealBackend

public abstract class AbstractNativeCPULinearAlgebraBackend<E>
extends Object
implements LinearAlgebraProvider<E>, NativeBackend, CPUBackend

Standalone Native Linear Algebra backend using bundled episteme_native library.

Since:

1.1

Author:

Silvere Martin-Michiellot, Gemini AI (Google DeepMind)

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CblasColMajor
static final int	CblasConjTrans
static final int	CblasLeft
static final int	CblasLower
static final int	CblasNonUnit
static final int	CblasNoTrans
static final int	CblasRight
static final int	CblasRowMajor
static final int	CblasTrans
static final int	CblasUnit
static final int	CblasUpper
static final int	LAPACK_COL_MAJOR
static final int	LAPACK_ROW_MAJOR
protected final Ring<E>	ring

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractNativeCPULinearAlgebraBackend(Ring<E> ring)

Method Summary

Modifier and Type	Method	Description
Matrix<E>	acos(Matrix<E> m)
Matrix<E>	acosh(Matrix<E> m)
Matrix<E>	add(Matrix<E> a, Matrix<E> b)
E	angle(Vector<E> a, Vector<E> b)	Returns the angle between two vectors in radians.
Matrix<E>	asin(Matrix<E> m)
Matrix<E>	asinh(Matrix<E> m)
Matrix<E>	atan(Matrix<E> m)
Matrix<E>	atanh(Matrix<E> m)
Matrix<E>	cbrt(Matrix<E> m)
CholeskyResult<E>	cholesky(Matrix<E> a)	Computes the Cholesky decomposition of the specified matrix.
Matrix<E>	cos(Matrix<E> m)
Matrix<E>	cosh(Matrix<E> m)
Object	createBackend()	Creates and returns the backend instance (or returns self if it is the backend).
ExecutionContext	createContext()	Creates an execution context for running operations.
Vector<E>	cross(Vector<E> a, Vector<E> b)	Returns the cross product of two 3D vectors.
double	ddot(int n, DoubleBuffer x, int incx, DoubleBuffer y, int incy)
E	determinant(Matrix<E> a)
int	dgels(char trans, int m, int n, int nrhs, DoubleBuffer A, int lda, DoubleBuffer B, int ldb)
void	dgemm(int m, int n, int k, DoubleBuffer A, int lda, DoubleBuffer B, int ldb, DoubleBuffer C, int ldc, double alpha, double beta)
void	dgemv(int m, int n, double alpha, DoubleBuffer A, int lda, DoubleBuffer x, int incx, double beta, DoubleBuffer y, int incy)
int	dgeqrf(int m, int n, DoubleBuffer A, int lda, DoubleBuffer tau)
int	dgesv(int n, int nrhs, DoubleBuffer A, int lda, IntBuffer ipiv, DoubleBuffer B, int ldb)
int	dgesvd(byte jobu, byte jobvt, int m, int n, DoubleBuffer A, int lda, DoubleBuffer S, DoubleBuffer U, int ldu, DoubleBuffer VT, int ldvt, DoubleBuffer superb)
int	dgetrf(int m, int n, DoubleBuffer A, int lda, IntBuffer ipiv)
int	dgetri(int n, DoubleBuffer A, int lda, IntBuffer ipiv)
double	dnrm2(int n, DoubleBuffer x, int incx)
int	dorgqr(int m, int n, int k, DoubleBuffer A, int lda, DoubleBuffer tau)
E	dot(Vector<E> a, Vector<E> b)
int	dpotrf(int n, DoubleBuffer A, int lda)
void	dscal(int n, double alpha, DoubleBuffer x, int incx)
int	dsyev(int n, DoubleBuffer A, int lda, DoubleBuffer W)
EigenResult<E>	eigen(Matrix<E> a)	Computes the eigenvalue decomposition of the specified matrix.
Matrix<E>	exp(Matrix<E> m)	Computes the matrix exponential e^A.
List<AlgorithmProvider>	getAlgorithmProviders()	Returns the AlgorithmProviders exposed by this backend.
String	getDescription()	Returns a description of the backend.
String	getEnvironmentInfo()	Returns a string describing the execution environment (e.g., "CPU (AVX2)", "GPU (CUDA 12.0)").
String	getId()	Returns the unique identifier for this backend (e.g., "javafx", "jmol", "cuda").
String	getName()	Returns the display name for UI presentation.
String	getNativeLibraryName()	Returns the name of the native library this backend depends on.
int	getPriority()	Priority of this provider (higher means more preferred).
String	getStatusMessage()	Returns a human-readable status message for this backend.
String	getType()	Returns the backend type category (e.g., "plotting", "molecular", "tensor", "math").
Matrix<E>	inverse(Matrix<E> a)
boolean	isAvailable()	Checks if the provider is available in the current environment.
boolean	isCompatible(Ring<?> ring)	Checks if this provider is compatible with the given ring.
boolean	isExplicitlyDisabled()	Checks if this backend is specifically disabled via a system property: "episteme.backend.disable." + getId().
boolean	isLoaded()	Checks if the native library is loaded and available.
Matrix<E>	log(Matrix<E> m)
Matrix<E>	log10(Matrix<E> m)
LUResult<E>	lu(Matrix<E> a)	Computes the LU decomposition of the specified matrix.
Matrix<E>	multiply(Matrix<E> a, Matrix<E> b)
Vector<E>	multiply(Matrix<E> a, Vector<E> b)
Vector<E>	multiply(Vector<E> vector, E scalar)
E	norm(Vector<E> a)
Vector<E>	normalize(Vector<E> v)	Returns the normalized vector (unit vector).
Matrix<E>	pow(Matrix<E> m, E exponent)
Vector<E>	projection(Vector<E> a, Vector<E> b)	Returns the projection of vector a onto vector b.
QRResult<E>	qr(Matrix<E> a)	Computes the QR decomposition of the specified matrix.
Matrix<E>	scale(E scalar, Matrix<E> a)
double	score(OperationContext context)	Scores this provider for a specific operation context.
void	shutdown()	Called when the provider is no longer needed (e.g., application shutdown).
Matrix<E>	sin(Matrix<E> m)
Matrix<E>	sinh(Matrix<E> m)
Vector<E>	solve(Matrix<E> a, Vector<E> b)
Vector<E>	solveTriangular(Matrix<E> A, Vector<E> b, boolean upper, boolean transpose, boolean conjugate, boolean unit)	Solves the triangular system Ax = b.
Matrix<E>	sqrt(Matrix<E> m)
Matrix<E>	subtract(Matrix<E> a, Matrix<E> b)
SVDResult<E>	svd(Matrix<E> a)	Computes the Singular Value Decomposition (SVD) of the specified matrix.
Matrix<E>	tan(Matrix<E> m)
Matrix<E>	tanh(Matrix<E> m)
E	trace(Matrix<E> a)
Matrix<E>	transpose(Matrix<E> a)
int	zgeqrf(int m, int n, DoubleBuffer A, int lda, DoubleBuffer tau)
int	zgesvd(byte jobu, byte jobvt, int m, int n, DoubleBuffer A, int lda, DoubleBuffer S, DoubleBuffer U, int ldu, DoubleBuffer VT, int ldvt, DoubleBuffer superb)
int	zungqr(int m, int n, int k, DoubleBuffer A, int lda, DoubleBuffer tau)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface AlgorithmProvider

description, getMetadata

Methods inherited from interface CPUBackend

getAcceleratorType, supportsComplexNumbers, supportsFloatingPoint, supportsParallelOps

Methods inherited from interface LinearAlgebraProvider

add, close, conditionNumber, configure, conjugateTranspose, getAlgorithmType, rank, solve, solve, solve, subtract

Field Details

CblasRowMajor

public static final int CblasRowMajor

See Also:

• Constant Field Values

CblasColMajor

public static final int CblasColMajor

See Also:

• Constant Field Values

CblasNoTrans

public static final int CblasNoTrans

See Also:

• Constant Field Values

CblasTrans

public static final int CblasTrans

See Also:

• Constant Field Values

CblasConjTrans

public static final int CblasConjTrans

See Also:

• Constant Field Values

CblasUpper

public static final int CblasUpper

See Also:

• Constant Field Values

CblasLower

public static final int CblasLower

See Also:

• Constant Field Values

CblasUnit

public static final int CblasUnit

See Also:

• Constant Field Values

CblasNonUnit

public static final int CblasNonUnit

See Also:

• Constant Field Values

CblasLeft

public static final int CblasLeft

See Also:

• Constant Field Values

CblasRight

public static final int CblasRight

See Also:

• Constant Field Values

LAPACK_ROW_MAJOR

public static final int LAPACK_ROW_MAJOR

See Also:

• Constant Field Values

LAPACK_COL_MAJOR

public static final int LAPACK_COL_MAJOR

See Also:

• Constant Field Values

ring

protected final Ring<E> ring

Constructor Details

AbstractNativeCPULinearAlgebraBackend

protected AbstractNativeCPULinearAlgebraBackend(Ring<E> ring)

Method Details

isLoaded

public boolean isLoaded()

Description copied from interface: NativeBackend

Checks if the native library is loaded and available.

Specified by:

isLoaded in interface NativeBackend

Returns:

true if the native library has been successfully loaded

getNativeLibraryName

public String getNativeLibraryName()

Description copied from interface: NativeBackend

Returns the name of the native library this backend depends on.

Specified by:

getNativeLibraryName in interface NativeBackend

Returns:

library name (e.g., "openblas", "cuda", "fftw3")

isAvailable

public boolean isAvailable()

Description copied from interface: AlgorithmProvider

Checks if the provider is available in the current environment.

Specified by:

isAvailable in interface AlgorithmProvider

Specified by:

isAvailable in interface Backend

isExplicitlyDisabled

public boolean isExplicitlyDisabled()

Description copied from interface: Backend

Checks if this backend is specifically disabled via a system property: "episteme.backend.disable." + getId().

It also checks specialized properties like "episteme.linearalgebra.disable." + getId().

Specified by:

isExplicitlyDisabled in interface Backend

Returns:

true if explicitly disabled

getId

public String getId()

Description copied from interface: Backend

Returns the unique identifier for this backend (e.g., "javafx", "jmol", "cuda").

Specified by:

getId in interface Backend

Specified by:

getId in interface ComputeBackend

getType

public String getType()

Description copied from interface: Backend

Returns the backend type category (e.g., "plotting", "molecular", "tensor", "math").

Specified by:

getType in interface Backend

Specified by:

getType in interface ComputeBackend

Specified by:

getType in interface CPUBackend

getStatusMessage

public String getStatusMessage()

Description copied from interface: Backend

Returns a human-readable status message for this backend. Useful for debugging "Unavailable" states.

Specified by:

getStatusMessage in interface Backend

Returns:

status message (e.g., "Ready", "Native library missing", etc.)

getEnvironmentInfo

public String getEnvironmentInfo()

Description copied from interface: LinearAlgebraProvider

Returns a string describing the execution environment (e.g., "CPU (AVX2)", "GPU (CUDA 12.0)").

Specified by:

getEnvironmentInfo in interface LinearAlgebraProvider<E>

getName

public String getName()

Description copied from interface: Backend

Returns the display name for UI presentation.

Specified by:

getName in interface AlgorithmProvider

Specified by:

getName in interface Backend

Specified by:

getName in interface LinearAlgebraProvider<E>

getDescription

public String getDescription()

Description copied from interface: Backend

Returns a description of the backend.

Specified by:

getDescription in interface Backend

Specified by:

getDescription in interface ComputeBackend

getPriority

public int getPriority()

Description copied from interface: LinearAlgebraProvider

Priority of this provider (higher means more preferred). Used for automatic backend selection.

Specified by:

getPriority in interface AlgorithmProvider

Specified by:

getPriority in interface Backend

Specified by:

getPriority in interface LinearAlgebraProvider<E>

createBackend

public Object createBackend()

Description copied from interface: Backend

Creates and returns the backend instance (or returns self if it is the backend).

Specified by:

createBackend in interface Backend

Specified by:

createBackend in interface ComputeBackend

Returns:

The backend implementation object

getAlgorithmProviders

public List<AlgorithmProvider> getAlgorithmProviders()

Description copied from interface: Backend

Returns the AlgorithmProviders exposed by this backend.

This bridges the Backend discovery system (ServiceLoader<Backend>) with the Algorithm discovery system (ServiceLoader<AlgorithmProvider>), allowing AlgorithmManager to find providers registered through either path.

Default implementation checks if Backend.createBackend() returns an AlgorithmProvider instance.

Specified by:

getAlgorithmProviders in interface Backend

Returns:

list of algorithm providers (may be empty, never null)

score

public double score(OperationContext context)

Description copied from interface: AlgorithmProvider

Scores this provider for a specific operation context.

Higher scores indicate better suitability. Used by ProviderSelector for context-aware selection.

Default implementation returns AlgorithmProvider.getPriority(), so existing providers behave identically without changes.

Specified by:

score in interface AlgorithmProvider

Specified by:

score in interface LinearAlgebraProvider<E>

Parameters:

context - the operation context (data size, hints, etc.)

Returns:

suitability score (higher = better)

isCompatible

public boolean isCompatible(Ring<?> ring)

Description copied from interface: LinearAlgebraProvider

Checks if this provider is compatible with the given ring.

Specified by:

isCompatible in interface LinearAlgebraProvider<E>

createContext

public ExecutionContext createContext()

Description copied from interface: ComputeBackend

Creates an execution context for running operations.

The context should be used within a try-with-resources block to ensure proper cleanup of resources.

Specified by:

createContext in interface ComputeBackend

Returns:

new execution context

solveTriangular

public Vector<E> solveTriangular(Matrix<E> A,
 Vector<E> b,
 boolean upper,
 boolean transpose,
 boolean conjugate,
 boolean unit)

Description copied from interface: LinearAlgebraProvider

Solves the triangular system Ax = b.

Specified by:

solveTriangular in interface LinearAlgebraProvider<E>

Parameters:

A - the triangular matrix

b - the right-hand side vector

upper - true if A is upper triangular, false if lower

transpose - true if solving A^T x = b

conjugate - true if solving A^H x = b (only if transpose is true and complex)

unit - true if A is unit triangular (diagonal is all ones)

dgemm

public void dgemm(int m,
 int n,
 int k,
 DoubleBuffer A,
 int lda,
 DoubleBuffer B,
 int ldb,
 DoubleBuffer C,
 int ldc,
 double alpha,
 double beta)

dgemv

public void dgemv(int m,
 int n,
 double alpha,
 DoubleBuffer A,
 int lda,
 DoubleBuffer x,
 int incx,
 double beta,
 DoubleBuffer y,
 int incy)

ddot

public double ddot(int n,
 DoubleBuffer x,
 int incx,
 DoubleBuffer y,
 int incy)

dnrm2

public double dnrm2(int n,
 DoubleBuffer x,
 int incx)

dscal

public void dscal(int n,
 double alpha,
 DoubleBuffer x,
 int incx)

dgetrf

public int dgetrf(int m,
 int n,
 DoubleBuffer A,
 int lda,
 IntBuffer ipiv)

dgetri

public int dgetri(int n,
 DoubleBuffer A,
 int lda,
 IntBuffer ipiv)

dgesv

public int dgesv(int n,
 int nrhs,
 DoubleBuffer A,
 int lda,
 IntBuffer ipiv,
 DoubleBuffer B,
 int ldb)

dsyev

public int dsyev(int n,
 DoubleBuffer A,
 int lda,
 DoubleBuffer W)

dpotrf

public int dpotrf(int n,
 DoubleBuffer A,
 int lda)

dgeqrf

public int dgeqrf(int m,
 int n,
 DoubleBuffer A,
 int lda,
 DoubleBuffer tau)

dorgqr

public int dorgqr(int m,
 int n,
 int k,
 DoubleBuffer A,
 int lda,
 DoubleBuffer tau)

dgesvd

public int dgesvd(byte jobu,
 byte jobvt,
 int m,
 int n,
 DoubleBuffer A,
 int lda,
 DoubleBuffer S,
 DoubleBuffer U,
 int ldu,
 DoubleBuffer VT,
 int ldvt,
 DoubleBuffer superb)

zgeqrf

public int zgeqrf(int m,
 int n,
 DoubleBuffer A,
 int lda,
 DoubleBuffer tau)

zungqr

public int zungqr(int m,
 int n,
 int k,
 DoubleBuffer A,
 int lda,
 DoubleBuffer tau)

zgesvd

public int zgesvd(byte jobu,
 byte jobvt,
 int m,
 int n,
 DoubleBuffer A,
 int lda,
 DoubleBuffer S,
 DoubleBuffer U,
 int ldu,
 DoubleBuffer VT,
 int ldvt,
 DoubleBuffer superb)

dgels

public int dgels(char trans,
 int m,
 int n,
 int nrhs,
 DoubleBuffer A,
 int lda,
 DoubleBuffer B,
 int ldb)

multiply

public Vector<E> multiply(Matrix<E> a,
 Vector<E> b)

Specified by:

multiply in interface LinearAlgebraProvider<E>

shutdown

public void shutdown()

Description copied from interface: AlgorithmProvider

Called when the provider is no longer needed (e.g., application shutdown). Use this to release local resources or close native segments.

Specified by:

shutdown in interface AlgorithmProvider

Specified by:

shutdown in interface Backend

add

public Matrix<E> add(Matrix<E> a,
 Matrix<E> b)

Specified by:

add in interface LinearAlgebraProvider<E>

subtract

public Matrix<E> subtract(Matrix<E> a,
 Matrix<E> b)

Specified by:

subtract in interface LinearAlgebraProvider<E>

scale

public Matrix<E> scale(E scalar,
 Matrix<E> a)

Specified by:

scale in interface LinearAlgebraProvider<E>

multiply

public Matrix<E> multiply(Matrix<E> a,
 Matrix<E> b)

Specified by:

multiply in interface LinearAlgebraProvider<E>

inverse

public Matrix<E> inverse(Matrix<E> a)

Specified by:

inverse in interface LinearAlgebraProvider<E>

solve

public Vector<E> solve(Matrix<E> a,
 Vector<E> b)

Specified by:

solve in interface LinearAlgebraProvider<E>

transpose

public Matrix<E> transpose(Matrix<E> a)

Specified by:

transpose in interface LinearAlgebraProvider<E>

determinant

public E determinant(Matrix<E> a)

Specified by:

determinant in interface LinearAlgebraProvider<E>

lu

public LUResult<E> lu(Matrix<E> a)

Description copied from interface: LinearAlgebraProvider

Computes the LU decomposition of the specified matrix.

Specified by:

lu in interface LinearAlgebraProvider<E>

eigen

public EigenResult<E> eigen(Matrix<E> a)

Description copied from interface: LinearAlgebraProvider

Computes the eigenvalue decomposition of the specified matrix.

Specified by:

eigen in interface LinearAlgebraProvider<E>

cholesky

public CholeskyResult<E> cholesky(Matrix<E> a)

Description copied from interface: LinearAlgebraProvider

Computes the Cholesky decomposition of the specified matrix.

Specified by:

cholesky in interface LinearAlgebraProvider<E>

dot

public E dot(Vector<E> a,
 Vector<E> b)

Specified by:

dot in interface LinearAlgebraProvider<E>

norm

public E norm(Vector<E> a)

Specified by:

norm in interface LinearAlgebraProvider<E>

normalize

public Vector<E> normalize(Vector<E> v)

Description copied from interface: LinearAlgebraProvider

Returns the normalized vector (unit vector).

Specified by:

normalize in interface LinearAlgebraProvider<E>

cross

public Vector<E> cross(Vector<E> a,
 Vector<E> b)

Description copied from interface: LinearAlgebraProvider

Returns the cross product of two 3D vectors.

Specified by:

cross in interface LinearAlgebraProvider<E>

angle

public E angle(Vector<E> a,
 Vector<E> b)

Description copied from interface: LinearAlgebraProvider

Returns the angle between two vectors in radians.

Specified by:

angle in interface LinearAlgebraProvider<E>

projection

public Vector<E> projection(Vector<E> a,
 Vector<E> b)

Description copied from interface: LinearAlgebraProvider

Returns the projection of vector a onto vector b.

Specified by:

projection in interface LinearAlgebraProvider<E>

multiply

public Vector<E> multiply(Vector<E> vector,
 E scalar)

Specified by:

multiply in interface LinearAlgebraProvider<E>

qr

public QRResult<E> qr(Matrix<E> a)

Description copied from interface: LinearAlgebraProvider

Computes the QR decomposition of the specified matrix.

Specified by:

qr in interface LinearAlgebraProvider<E>

svd

public SVDResult<E> svd(Matrix<E> a)

Description copied from interface: LinearAlgebraProvider

Computes the Singular Value Decomposition (SVD) of the specified matrix.

Specified by:

svd in interface LinearAlgebraProvider<E>

trace

public E trace(Matrix<E> a)

Specified by:

trace in interface LinearAlgebraProvider<E>

exp

public Matrix<E> exp(Matrix<E> m)

Description copied from interface: LinearAlgebraProvider

Computes the matrix exponential e^A.

Specified by:

exp in interface LinearAlgebraProvider<E>

log

public Matrix<E> log(Matrix<E> m)

Specified by:

log in interface LinearAlgebraProvider<E>

log10

public Matrix<E> log10(Matrix<E> m)

Specified by:

log10 in interface LinearAlgebraProvider<E>

sin

public Matrix<E> sin(Matrix<E> m)

Specified by:

sin in interface LinearAlgebraProvider<E>

cos

public Matrix<E> cos(Matrix<E> m)

Specified by:

cos in interface LinearAlgebraProvider<E>

tan

public Matrix<E> tan(Matrix<E> m)

Specified by:

tan in interface LinearAlgebraProvider<E>

asin

public Matrix<E> asin(Matrix<E> m)

Specified by:

asin in interface LinearAlgebraProvider<E>

acos

public Matrix<E> acos(Matrix<E> m)

Specified by:

acos in interface LinearAlgebraProvider<E>

atan

public Matrix<E> atan(Matrix<E> m)

Specified by:

atan in interface LinearAlgebraProvider<E>

sinh

public Matrix<E> sinh(Matrix<E> m)

Specified by:

sinh in interface LinearAlgebraProvider<E>

cosh

public Matrix<E> cosh(Matrix<E> m)

Specified by:

cosh in interface LinearAlgebraProvider<E>

tanh

public Matrix<E> tanh(Matrix<E> m)

Specified by:

tanh in interface LinearAlgebraProvider<E>

asinh

public Matrix<E> asinh(Matrix<E> m)

Specified by:

asinh in interface LinearAlgebraProvider<E>

acosh

public Matrix<E> acosh(Matrix<E> m)

Specified by:

acosh in interface LinearAlgebraProvider<E>

atanh

public Matrix<E> atanh(Matrix<E> m)

Specified by:

atanh in interface LinearAlgebraProvider<E>

sqrt

public Matrix<E> sqrt(Matrix<E> m)

Specified by:

sqrt in interface LinearAlgebraProvider<E>

cbrt

public Matrix<E> cbrt(Matrix<E> m)

Specified by:

cbrt in interface LinearAlgebraProvider<E>

pow

public Matrix<E> pow(Matrix<E> m,
 E exponent)

Specified by:

pow in interface LinearAlgebraProvider<E>