|
| 1 | +# High Level Bindings |
| 2 | + |
| 3 | +The purpose of the high-level magicl bindings is to allow for MATLAB-like multidimensional arrays in lisp. |
| 4 | + |
| 5 | +## Constructors |
| 6 | + |
| 7 | +The construction of tensors can be done with any of the given constructors. The constructors take a shape and arguments for method of construction. |
| 8 | + |
| 9 | +Tensors are specialized on both the shape and the element type. The class of a tensor will be of the form `$CLASS/$TYPE` (e.g. `MATRIX/DOUBLE-FLOAT`). |
| 10 | + |
| 11 | +| Number of dimensions | Tensor Class | |
| 12 | +|----------------------|-----------------| |
| 13 | +| 1 | `VECTOR` | |
| 14 | +| 2 | `MATRIX` | |
| 15 | +| * | `TENSOR` | |
| 16 | + |
| 17 | +| Element Type | Class Suffix | |
| 18 | +|--------------------------|------------------------| |
| 19 | +| `SINGLE-FLOAT` | `SINGLE-FLOAT` | |
| 20 | +| `DOUBLE-FLOAT` | `DOUBLE-FLOAT` | |
| 21 | +| `(COMPLEX SINGLE-FLOAT)` | `COMPLEX-SINGLE-FLOAT` | |
| 22 | +| `(COMPLEX DOUBLE-FLOAT)` | `COMPLEX-DOUBLE-FLOAT` | |
| 23 | +| `(SIGNED-BYTE 32)` | `INT32` | |
| 24 | + |
| 25 | +The type of the elements of the tensor can be specified with the `:type` keyword, or the constructor will attempt to find an appropriate type from the given arguments. The default element type for a tensor is `DOUBLE-FLOAT`. |
| 26 | + |
| 27 | +The layout of the tensor (column-major or row-major) can be specified with the `:layout` keyword. This affects the underlying storage of the tensor and will affect how it carries out operations with LAPACK. |
| 28 | + |
| 29 | + |
| 30 | +## Other Library Equivalents |
| 31 | + |
| 32 | +This table was adapted largely from the [NumPy Equivalents Table](https://docs.scipy.org/doc/numpy/user/numpy-for-matlab-users.html#linear-algebra-equivalents). |
| 33 | + |
| 34 | +### Basic Accessors |
| 35 | + |
| 36 | +| MAGICL | MATLAB | NumPy | Description | |
| 37 | +|----------------|------------|-------------------------|---------------------------------------------------------------| |
| 38 | +| `(order a)` | `ndims(a)` | `ndim(a)` or `a.ndim` | Get the number of dimensions of the array. | |
| 39 | +| `(size a)` | `numel(a)` | `size(a)` or `a.size` | Get the number of elements of the array. | |
| 40 | +| `(shape a)` | `size(a)` | `shape(a)` or `a.shape` | Get the shape of the array. | |
| 41 | +| `(tref a 1 4)` | `a(2,5)` | `a[1, 4]` | Get the element in the second row, fifth column of the array. | |
| 42 | + |
| 43 | +### Constructors |
| 44 | + |
| 45 | +| MAGICL | MATLAB | NumPy | Description | |
| 46 | +|-------------------------------------------------|--------------------|-----------------------------------|--------------------------------------------------------------------------------------| |
| 47 | +| `(from-list '(1d0 2d0 3d0 4d0 5d0 6d0) '(2 3))` | `[ 1 2 3; 4 5 6 ]` | `array([[1.,2.,3.], [4.,5.,6.]])` | Create a 2x3 matrix from given elements. | |
| 48 | +| `(zeros '(2 3 4))` or `(const 0d0 '(2 3 4))` | `zeros(2,3,4)` | `zeros((2,3,4))` | Create a 2x3x4 dimensional array of zeroes of double-float element type. | |
| 49 | +| `(ones '(3 4)` or `(const 1d0 '(3 4))` | `ones(3,4)` | `ones((3,4))` | Create a 3x4 dimensional array of ones of double-float element type. | |
| 50 | +| `(eye 1d0 '(3 3))` | `eye(3)` | `eye(3)` | Create a 3x3 identity array of double-float element type. | |
| 51 | +| `(from-diag a)` | `diag(a)` | `diag(a)` | Create a square matrix from the diagonal entries in `a` with zeroes everywhere else. | |
| 52 | +| `(rand '(3 4))` | `rand(3,4)` | `random.rand(3,4)` | Create a random 3x4 array. | |
| 53 | + |
| 54 | +### Basic Operations |
| 55 | + |
| 56 | +| MAGICL | MATLAB | NumPy | Description | |
| 57 | +|------------|----------|------------------|-----------------------------| |
| 58 | +| `(@ a b)` | `a * b` | `a @ b` | Matrix multiplication | |
| 59 | +| `(.+ a b)` | `a + b` | `a + b` | Element-wise add | |
| 60 | +| `(.- a b)` | `a - b` | `a - b` | Element-wise subtract | |
| 61 | +| `(.* a b)` | `a .* b` | `a * b` | Element-wise multiply | |
| 62 | +| `(./ a b)` | `a./b` | `a/b` | Element-wise divide | |
| 63 | +| `(.^ a b)` | `a.^b` | `np.power(a,b)` | Element-wise exponentiation | |
| 64 | + |
| 65 | +### Linear Algebra |
| 66 | + |
| 67 | +| MAGICL | MATLAB | NumPy | Description | |
| 68 | +|---------------------------------------------------------|-------------------|----------------------------------------------------------------|--------------------------------------------| |
| 69 | +| `(det a)` | `det(a)` | `linalg.det(a)` | Determinant of matrix | |
| 70 | +| `(trace a)` | `trace(a)` | `trace(a)` | Trace (sum of diagonal elements) of matrix | |
| 71 | +| `(upper-triangular a)` | `triu(a)` | `triu(a)` | Upper triangular part of matrix | |
| 72 | +| `(lower-triangular a)` | `tril(a)` | `tril(a)` | Lower triangular part of matrix | |
| 73 | +| `(transpose a)` | `a.'` | `a.transpose()` or `a.T` | Transpose of matrix | |
| 74 | +| `(conjugate-transpose a)` or `(dagger a)` | `a'` | `a.conj().transpose()` or `a.H` | Conjugate transpose of matrix | |
| 75 | +| `(inv a)` | `inv(a)` | `linalg.inv(a)` | Inverse of matrix | |
| 76 | +| `(svd a)` (Returns `(VALUES U SIGMA Vt)`) | `[U,S,V]=svd(a)` | `U, S, Vh = linalg.svd(a), V = Vh.T` | Singular value decomposition of matrix | |
| 77 | +| `(eig a)` (Returns `(VALUES EIGENVALUES EIGENVECTORS)`) | `[V,D]=eig(a)` | `D,V = linalg.eig(a)` | Eigenvalues and eigenvectors of matrix | |
| 78 | +| `(qr a)` (Returns `(VALUES Q R)`) | `[Q,R,P]=qr(a,0)` | `Q,R = scipy.linalg.qr(a)` | QR factorization of matrix | |
| 79 | +| `(ql a)` (Returns `(VALUES Q L)`) | | | QL factorization of matrix | |
| 80 | +| `(rq a)` (Returns `(VALUES R Q)`) | | `R,Q = scipy.linalg.rq(a)` | RQ factorization of matrix | |
| 81 | +| `(lq a)` (Returns `(VALUES L Q)`) | | | LQ factorization of matrix | |
| 82 | +| `(lu a)` (Returns `(VALUES LU IPIV)`) | `[L,U,P]=lu(a)` | `L,U = scipy.linalg.lu(a)` or `LU,P=scipy.linalg.lu_factor(a)` | LU decomposition of matrix | |
| 83 | +| `(csd a)` (Returns `(VALUES U SIGMA VT)`) | | | Cosine-sine decomposition of matrix | |
0 commit comments