HMath.Backend¶
Module index · Numerical conventions
Description
Checked dense CPU kernels with explicit, garbage-collected provider handles. Inputs and outputs use private contiguous copies. No pointer escapes to the caller and the immutable matrices are never mutated. Auto selection tries OpenBLAS LP64, then the pure implementation; explicit selection never silently falls back. Provider paths are executable native libraries and must be trusted.
OpenBLAS reports its integer ABI via openblas_get_config; BLIS reports both query and BLAS integer widths. oneMKL's process-global interface layer is set on first explicit selection: applications sharing MKL must select this handle before other MKL use and must not change that layer afterwards. Accelerate's system CBLAS uses LP64. Thread setters affect the provider globally; callers serialize reconfiguration with other uses of that provider.
LAPACKE solve/spectral dispatch is independently configured by the environment documented in HMath.Matrix.LAPACK. LU factors, QR, Cholesky and least squares expose the checked pure reference algorithms; the provider affects BLAS kernels only. Batched operations loop over GEMM calls (no vendor batch-extension requirement).
On this page¶
| API | Purpose |
|---|---|
| Provider | Pure reference, OpenBLAS, BLIS, Intel oneMKL SDL, or Apple's system framework. |
| Pure | Declaration and type contract below. |
| OpenBLAS | Declaration and type contract below. |
| BLIS | Declaration and type contract below. |
| OneMKL | Declaration and type contract below. |
| Accelerate | Declaration and type contract below. |
| IntegerABI | BLAS/LAPACK integer width; Haskell dimensions must additionally fit Int. |
| LP64 | Declaration and type contract below. |
| ILP64 | Declaration and type contract below. |
| BackendRequest | Optional path overrides the provider default; Accelerate only accepts its system framework. |
| AutoBackend | Declaration and type contract below. |
| RequireBackend | Declaration and type contract below. |
| Backend | Opaque selected reference/native backend owner. |
| BackendInfo | Actual selected BLAS provider and integer-width ABI, available through backendInfo. |
| BackendInfo | Declaration and type contract below. |
| selectedProvider | Provider actually selected, including Pure when reference fallback is used. |
| selectedIntegerABI | Selected BLAS integer width: LP64 uses 32-bit indices and ILP64 uses 64-bit indices. |
| selectBackend | Given AutoBackend or explicit providerinteger-ABIlibrary request, select a reference or native BLAS backend in IO. |
| backendInfo | Provider identity is immutable for the lifetime of a handle. |
| pureBackend | Construct the deterministic reference backend without dynamically loading BLAS. |
| setBackendThreads | Positive thread count; Pure supports one thread. |
| lapackAvailable | Availability of the once-initialized independent LAPACKE loader. |
| BackendLayout | Physical matrix storage order: RowMajor or ColumnMajor, independent of mathematical transpose. |
| RowMajor | Declaration and type contract below. |
| ColumnMajor | Declaration and type contract below. |
| Transpose | BLAS operand transformation: unchanged,transposed,or conjugate-transposed. |
| NoTranspose | Declaration and type contract below. |
| Transpose | Declaration and type contract below. |
| ConjugateTranspose | Declaration and type contract below. |
| matrixFromLayout | Layout conversion is a checked, explicit copy; zero shapes retain rank. |
| matrixToLayout | Given RowMajor/ColumnMajor layout then Matrix, return values in that physical order without changing the logical matrix. |
| axpy | Given backend,alpha,x,y, return alpha*x+y as a new Double list. |
| dot | Real inner product. |
| nrm2 | Given backend then finite Double vector, return Euclidean norm through the selected provider or reference path. |
| gemv | y := alpha op(A) x + beta y. |
| gemm | C := alpha op(A) op(B) + beta C. |
| complexAxpy | Given backend,complex alpha,x,y, compute alpha*x+y, requiring equal lengths and finite realimaginary components. |
| complexDot | Set the Boolean to True for the Hermitian dot product (conjugate x). |
| complexNrm2 | Given backend then complex vector, return real Euclidean norm of all real/imaginary components. |
| complexGemv | Given backend,transpose selector,alpha,A,x,beta,y, return alphaop(A)x+beta*y as a new complex list. |
| complexGemm | Given backend,transpose A,transpose B,alpha,A,B,beta,C, return alphaop(A)op(B)+beta*C as a new complex matrix. |
| batchedGemm | Uniform scalar/transpose options, independently checked matrix triples. |
| stridedBatchedGemm | Row-major batches of A(m,k) and B(k,n). |
| backendLU | Given backend then real matrix, compute checked column-independent LU using the reference pivoted LU implementation. |
| backendQR | Given backend then real matrix, compute reference column-pivoted Householder QR; selection does not change this routine's provider. |
| backendSolve | Given backend,square real matrix,then RHS list, solve via reference LU for Pure or the independent LAPACKE solve bridge for a native backend. |
| backendCholesky | Given backend then finite symmetric positive-definite matrix, return reference lower Cholesky factor. |
| backendLeastSquares | Given backend,design matrix,then RHS list, solve using reference pivoted QR. |
| backendSVD | Given backend then finite real matrix, use bounded pure reference SVD for Pure or LAPACK thin SVD for native selection. |
| backendSymmetricEigen | Given backend then finite symmetric square matrix, use bounded cyclic-Jacobi reference solver for Pure or LAPACK otherwise. |
| pureSVD | Thin real SVD by one-sided Jacobi orthogonalization, at most 100 sweeps, dimensions <=128. |
| pureSymmetricEigen | Cyclic Jacobi symmetric eigensolver, at most 100 sweeps, ascending eigenvalues. |
| lapackStatus | Convert the LAPACK convention without losing the distinction between an invalid argument and failed numerical convergence. |
Documentation
Provider
Pure reference, OpenBLAS, BLIS, Intel oneMKL SDL, or Apple's system framework.
Constructors
| Pure | |
| OpenBLAS | |
| BLIS | |
| OneMKL | |
| Accelerate |
Instances
| Enum Provider Source # | |
| Show Provider Source # | |
| Eq Provider Source # | |
| Ord Provider Source # | |
Defined in HMath.Backend | |
IntegerABI
data IntegerABI Source #
BLAS/LAPACK integer width; Haskell dimensions must additionally fit Int.
Instances
| Show IntegerABI Source # | |
Defined in HMath.Backend Methods showsPrec :: Int -> IntegerABI -> ShowS # show :: IntegerABI -> String # showList :: [IntegerABI] -> ShowS # | |
| Eq IntegerABI Source # | |
Defined in HMath.Backend | |
| Ord IntegerABI Source # | |
Defined in HMath.Backend Methods compare :: IntegerABI -> IntegerABI -> Ordering # (<) :: IntegerABI -> IntegerABI -> Bool # (<=) :: IntegerABI -> IntegerABI -> Bool # (>) :: IntegerABI -> IntegerABI -> Bool # (>=) :: IntegerABI -> IntegerABI -> Bool # max :: IntegerABI -> IntegerABI -> IntegerABI # min :: IntegerABI -> IntegerABI -> IntegerABI # | |
BackendRequest
data BackendRequest Source #
Optional path overrides the provider default; Accelerate only accepts its system framework. OpenBLAS custom symbol prefixes are unsupported; the usual unsuffixed and 64_ suffixed builds are recognized.
Constructors
| AutoBackend | |
| RequireBackend Provider IntegerABI (Maybe FilePath) |
Instances
| Show BackendRequest Source # | |
Defined in HMath.Backend Methods showsPrec :: Int -> BackendRequest -> ShowS # show :: BackendRequest -> String # showList :: [BackendRequest] -> ShowS # | |
| Eq BackendRequest Source # | |
Defined in HMath.Backend Methods (==) :: BackendRequest -> BackendRequest -> Bool # (/=) :: BackendRequest -> BackendRequest -> Bool # | |
Backend
Opaque selected reference/native backend owner. Retain the value while using its dynamically loaded provider.
BackendInfo
data BackendInfo Source #
Actual selected BLAS provider and integer-width ABI, available through backendInfo.
Constructors
| BackendInfo | |
Fields
| |
Instances
| Show BackendInfo Source # | |
Defined in HMath.Backend Methods showsPrec :: Int -> BackendInfo -> ShowS # show :: BackendInfo -> String # showList :: [BackendInfo] -> ShowS # | |
| Eq BackendInfo Source # | |
Defined in HMath.Backend | |
selectBackend
selectBackend :: BackendRequest -> IO (Either MathError Backend) Source #
Given AutoBackend or explicit providerinteger-ABIlibrary request, select a reference or native BLAS backend in IO. Auto honors HMATH_BACKEND, HMATH_BLAS_PROVIDER, HMATH_BLAS_INTEGER_BITS and HMATH_BLAS_LIBRARY; unknown settings or unavailable explicit providers fail. Keep the Backend alive while calling it.
backendInfo
backendInfo :: Backend -> BackendInfo Source #
Provider identity is immutable for the lifetime of a handle.
pureBackend
pureBackend :: Backend Source #
Construct the deterministic reference backend without dynamically loading BLAS. Its lifetime is garbage-collected; selected numeric reference decomposition limits still apply.
setBackendThreads
setBackendThreads :: Backend -> Int -> IO (Either MathError ()) Source #
Positive thread count; Pure supports one thread. Accelerate has no supported runtime setter and returns an explicit error. No implicit global restoration.
lapackAvailable
lapackAvailable :: IO Bool Source #
Availability of the once-initialized independent LAPACKE loader.
BackendLayout
data BackendLayout Source #
Physical matrix storage order: RowMajor or ColumnMajor, independent of mathematical transpose.
Constructors
| RowMajor | |
| ColumnMajor |
Instances
| Show BackendLayout Source # | |
Defined in HMath.Backend Methods showsPrec :: Int -> BackendLayout -> ShowS # show :: BackendLayout -> String # showList :: [BackendLayout] -> ShowS # | |
| Eq BackendLayout Source # | |
Defined in HMath.Backend Methods (==) :: BackendLayout -> BackendLayout -> Bool # (/=) :: BackendLayout -> BackendLayout -> Bool # | |
Transpose
BLAS operand transformation: unchanged,transposed,or conjugate-transposed.
Constructors
| NoTranspose | |
| Transpose | |
| ConjugateTranspose |
Instances
matrixFromLayout
matrixFromLayout :: BackendLayout -> Int -> Int -> [a] -> Either MathError (Matrix a) Source #
Layout conversion is a checked, explicit copy; zero shapes retain rank.
matrixToLayout
matrixToLayout :: BackendLayout -> Matrix a -> [a] Source #
Given RowMajor/ColumnMajor layout then Matrix, return values in that physical order without changing the logical matrix.
axpy
axpy :: Backend -> Double -> [Double] -> [Double] -> IO (Either MathError [Double]) Source #
Given backend,alpha,x,y, return alpha*x+y as a new Double list. Require equal lengths, finite inputsresult and provider-supported integer extents; validationprovider failures return Left MathError in IO.
dot
dot :: Backend -> [Double] -> [Double] -> IO (Either MathError Double) Source #
Real inner product. Finite input and output; accumulation can overflow even when exact cancellation would produce a finite mathematical result.
nrm2
nrm2 :: Backend -> [Double] -> IO (Either MathError Double) Source #
Given backend then finite Double vector, return Euclidean norm through the selected provider or reference path. Empty input gives zero; invalid/non-finite output or provider bounds fail in IO.
gemv
gemv :: Backend -> Transpose -> Double -> Matrix Double -> [Double] -> Double -> [Double] -> IO (Either MathError [Double]) Source #
y := alpha op(A) x + beta y. Finite inputs are checked even for zero alpha.
gemm
gemm :: Backend -> Transpose -> Transpose -> Double -> Matrix Double -> Matrix Double -> Double -> Matrix Double -> IO (Either MathError (Matrix Double)) Source #
C := alpha op(A) op(B) + beta C. Matrices and output must have compatible shapes; all zero-dimensional cases use the reference arithmetic.
complexAxpy
complexAxpy :: Backend -> Complex Double -> [Complex Double] -> [Complex Double] -> IO (Either MathError [Complex Double]) Source #
Given backend,complex alpha,x,y, compute alpha*x+y, requiring equal lengths and finite realimaginary components. Return a new list or checked shapeprovider/numeric error in IO.
complexDot
complexDot :: Backend -> Bool -> [Complex Double] -> [Complex Double] -> IO (Either MathError (Complex Double)) Source #
Set the Boolean to True for the Hermitian dot product (conjugate x).
complexNrm2
complexNrm2 :: Backend -> [Complex Double] -> IO (Either MathError Double) Source #
Given backend then complex vector, return real Euclidean norm of all real/imaginary components. Non-finite input/output or provider extent errors return Left MathError in IO.
complexGemv
complexGemv :: Backend -> Transpose -> Complex Double -> Matrix (Complex Double) -> [Complex Double] -> Complex Double -> [Complex Double] -> IO (Either MathError [Complex Double]) Source #
Given backend,transpose selector,alpha,A,x,beta,y, return alpha*op(A)*x+beta*y as a new complex list. ConjugateTranspose conjugates matrix values; dimensions, finite values and provider bounds are checked.
complexGemm
complexGemm :: Backend -> Transpose -> Transpose -> Complex Double -> Matrix (Complex Double) -> Matrix (Complex Double) -> Complex Double -> Matrix (Complex Double) -> IO (Either MathError (Matrix (Complex Double))) Source #
Given backend,transpose A,transpose B,alpha,A,B,beta,C, return alpha*op(A)*op(B)+beta*C as a new complex matrix. Validate compatible dimensions, finite components and provider integer/allocation bounds.
batchedGemm
batchedGemm :: Backend -> Transpose -> Transpose -> Double -> Double -> [(Matrix Double, Matrix Double, Matrix Double)] -> IO (Either MathError [Matrix Double]) Source #
Uniform scalar/transpose options, independently checked matrix triples. Earlier calls may execute before a later invalid item; no input is mutated.
stridedBatchedGemm
stridedBatchedGemm :: Backend -> Int -> Int -> Int -> Int -> Int -> [Double] -> Int -> [Double] -> IO (Either MathError [Matrix Double]) Source #
Row-major batches of A(m,k) and B(k,n). Strides count elements, may include padding, and may be zero for broadcast. Extents are checked with Integer before slicing; output batches are contiguous m*n matrices. No implicit transposes.
backendLU
backendLU :: Backend -> Matrix Double -> Either MathError (LU Double) Source #
Given backend then real matrix, compute checked column-independent LU using the reference pivoted LU implementation. The backend argument does not change this routine's provider. Shapepivotnumeric failures propagate.
backendQR
backendQR :: Backend -> Matrix Double -> Either MathError (QR Double) Source #
Given backend then real matrix, compute reference column-pivoted Householder QR; selection does not change this routine's provider. Validation/numeric errors propagate.
backendSolve
backendSolve :: Backend -> Matrix Double -> [Double] -> Either MathError [Double] Source #
Given backend,square real matrix,then RHS list, solve via reference LU for Pure or the independent LAPACKE solve bridge for a native backend. Invalid dimensions, unavailable solver, singularity or non-finite arithmetic returns Left MathError.
backendCholesky
backendCholesky :: Backend -> Matrix Double -> Either MathError (Matrix Double) Source #
Given backend then finite symmetric positive-definite matrix, return reference lower Cholesky factor. Invalid shapesymmetrypivots/numeric results fail; provider selection is not used by this wrapper.
backendLeastSquares
backendLeastSquares :: Backend -> Matrix Double -> [Double] -> Either MathError [Double] Source #
Given backend,design matrix,then RHS list, solve using reference pivoted QR. Require compatible overdeterminedfull-rank input; shaperank/numeric failures propagate.
backendSVD
backendSVD :: Backend -> Matrix Double -> Either MathError SVD Source #
Given backend then finite real matrix, use bounded pure reference SVD for Pure or LAPACK thin SVD for native selection. Return factors or checked shapebudgetprovider/convergence errors.
backendSymmetricEigen
backendSymmetricEigen :: Backend -> Matrix Double -> Either MathError Eigen Source #
Given backend then finite symmetric square matrix, use bounded cyclic-Jacobi reference solver for Pure or LAPACK otherwise. Return eigenvalues/vectors or inputproviderconvergence errors.
pureSVD
pureSVD :: Matrix Double -> Either MathError SVD Source #
Thin real SVD by one-sided Jacobi orthogonalization, at most 100 sweeps, dimensions <=128. Unlike a normal-equation SVD it does not form A^T A. A deterministic orthogonal completion supplies zero-singular-value columns.
pureSymmetricEigen
pureSymmetricEigen :: Matrix Double -> Either MathError Eigen Source #
Cyclic Jacobi symmetric eigensolver, at most 100 sweeps, ascending eigenvalues. Scaled input avoids squared-norm overflow. This reference path is limited to order 128 and reports nonconvergence rather than returning an unchecked factor.