MAT manual

Table of Contents

[in package MGL-MAT]

1 mgl-mat ASDF System Details

2 Introduction

2.1 What's MAT?

MAT is library for working with multi-dimensional arrays which supports efficient interfacing to foreign and CUDA code with automatic translations between cuda, foreign and lisp storage. BLAS and CUBLAS bindings are available.

2.2 What kind of matrices are supported?

Currently only row-major single and double float matrices are supported, but it would be easy to add single and double precision complex types too. Other numeric types, such as byte and native integer, can be added too, but they are not supported by CUBLAS. There are no restrictions on the number of dimensions, and reshaping is possible. The CUBLAS functions operate on the visible portion of the matrix (which is subject to displacement and shaping), invisible elements are not affected.

2.3 Installation

All dependencies are in quicklisp except for cl-cuda whose official repository has not incorporated my changes yet, so you'll need my fork for the time being.

3 Basics

A MAT is a CUBE (see Cube manual) whose facets are different representations of numeric arrays. These facets can be accessed with WITH-FACETS with one of the following FACET-NAMEs:

4 Element types

5 Printing

6 Shaping

Reshaping and displacement of MAT objects works somewhat similarly to lisp arrays. The key difference is that they are destructive operations. See RESHAPE-AND-DISPLACE!, RESHAPE!, DISPLACE!, RESHAPE-TO-ROW-MATRIX! and WITH-SHAPE-AND-DISPLACEMENT. ADJUST! is the odd one out, it may create a new MAT.

Existing facets are adjusted by all operations. For LISP-ARRAY facets, this means creating a new lisp array displaced to the backing array. The backing array stays the same, clients are supposed to observe MAT-DISPLACEMENT, MAT-DIMENSIONS or MAT-SIZE. The FOREIGN-ARRAY(0 1) and CUDA-ARRAY facets are OFFSET-POINTER's so displacement is done by changing the offset. Clients need to observe MAT-DIMENSIONS in any case.

7 Caching

Allocating and initializing a MAT object and its necessary facets can be expensive. The following macros remember the previous value of a binding in the same thread and lexical environment. Only weak references are constructed so the cached objects can be garbage collected.

While the cache is global, thread safety is guaranteed by having separate subcaches per thread. Each subcache is keyed by a gensym that's unique to each invocation of the caching macro, so different occurrences of caching macros in the source never share data. Still recursion could lead to data sharing between different invocations of the same function. To prevent this, the cached object is removed from the cache while it is used so other invocations will create a fresh one which isn't particularly efficient but at least it's safe.

8 Foreign arrays

One facet of MAT objects is FOREIGN-ARRAY which is backed by a memory area that can be pinned or is allocated in foreign memory depending on *FOREIGN-ARRAY-STRATEGY*.

9 CUDA

9.1 CUBLAS

WITH-CUDA should take of everything. No need to use these at all unless you have a very good reason to bypass it.

9.2 CURAND

This the low level CURAND API.

10 BLAS

Only some BLAS functions are implemented, but it should be easy to add more as needed. All of them default to using CUDA, if it is initialized and enabled (see USE-CUDA-P).

Level 1 BLAS operations

Level 3 BLAS operations

11 Destructive API

Finally, some neural network operations.

12 Non-destructive API

13 Mappings

14 Random numbers

This is rather experimental.

15 I/O

16 Extension API

Macros for defining cuda and lisp kernels. Typically operations have a cuda and a lisp implementations and decide which to use with USE-CUDA-P. These are provided to help writing new operations.


[generated by MGL-PAX]