MLX-CL
Common Lisp bindings for MLX

1. Convert from Lisp to mlx-array To convert between mlx-array and Lisp array (data containers), use generic function mlx-array:

   • scalar to mlx-array

     (mlx-array 2)
     

     array(2, dtype=int32)
     

   • list to mlx-array

     (mlx-array '((1 2) (3 4)))
     

     array([[1, 2],
            [3, 4]], dtype=uint64)
     

   • array to mlx-array

     (mlx-array #3A(((1 2) (3 4))
                    ((5 6) (7 8))))
     

     array([[[1, 2],
             [3, 4]],
            [[5, 6],
             [7, 8]]], dtype=uint64)
     

     note: use array, it's fast.

   You can implement methods to tell lisp how to convert your data into mlx-array.

2. Use lisp<- to convert mlx-array into Lisp value.

   For example:

   (lisp<- (mlx.rnd:randint 10 :shape #(5 5)))
   

   #2A((3 1 2 9 9) (8 9 0 1 1) (5 6 7 7 9) (3 4 5 2 7) (8 1 2 3 7))
   

3. Use (mlx-array pathname) to load mlx-array from pathname, how to load the mlx-array depends on the extension name of the pathname.

   For example, subsystem mlx-cl/io/npy provides NPY file I/O functionalities.

   (ql:quickload :mlx-cl/io/npy)
   

   If having a NPY file:

   import numpy as np
   
   np.save("./res/tmp/example.npy", np.array([[1, 2, 3], [4, 5, 6]], dtype=np.float32))
   

   (mlx-array "./res/tmp/example.npy")
   

   array([[1, 2, 3],
          [4, 5, 6]], dtype=float32)
   

   You could write mlx-array as NPY using save function:

   (->* (mlx-array #2A((1 2 3) (4 5 6)) :dtype :uint8)
     (save * :output "./res/tmp/example.npy"))
   

   ./res/tmp/example.npy
   

   import numpy as np
   
   print(np.load("./res/tmp/example.npy"))
   

   See I/O for more detailed description.

• Generate by range:

  • (arange [start] stop [step] &key step dtype)

    (arange 10)                             ; (arange STOP)
    

    array([0, 1, 2, ..., 7, 8, 9], dtype=float32)
    

    (arange 5 10)                           ; (arange START STOP)
    

    array([5, 6, 7, 8, 9], dtype=float32)
    

    (arange 2 10 2)                         ; (arange START STOP STEP)
    

    array([2, 4, 6, 8], dtype=float32)
    

  • (linspace start stop &optional num &key dtype)

    (linspace 0 10) ; num=50 by default
    

    array([0, 0.204082, 0.408163, ..., 9.59184, 9.79592, 10], dtype=float32)
    

• Generate array with constant values:

  • (zeros SHAPE &key DTYPE)
  • (ones SHAPE &key DTYPE)
  • (full SHAPE &optional VALUE &key DTYPE)

  (full '(5 5) 2333)
  

  array([[2333, 2333, 2333, 2333, 2333],
         [2333, 2333, 2333, 2333, 2333],
         [2333, 2333, 2333, 2333, 2333],
         [2333, 2333, 2333, 2333, 2333],
         [2333, 2333, 2333, 2333, 2333]], dtype=uint64)
  

• Generate coordinate grids:

  • (meshgrid arrays &key SPARES INDEXING)

    (meshgrid (arange -2 2)
              (arange -2 2))
    

    (array([[-2, -1, 0, 1],
           [-2, -1, 0, 1],
           [-2, -1, 0, 1],
           [-2, -1, 0, 1]], dtype=float32)
     array([[-2, -2, -2, -2],
           [-1, -1, -1, -1],
           [0, 0, 0, 0],
           [1, 1, 1, 1]], dtype=float32))
    

• at: API like Python's arr[...]

  • (at array &rest indexs)
  • (at* array &rest indexs) (alias for (lisp<- (at ...)))

  the indexs could be

  • (~ [start=0] stop [step=1] &key step)
    • (~ * * -1) (equal to (~ :step -1))
    • (~ 0 * -1) (equal to (~ 0 -1 -1))
    • (~ 5) (equal to (~ 0 5 1))
    • (~ ) or just ~ (equal to (~ 0 -1 -1))
  • integer
  • rational for first / last (negative) parts of axis
  • keywords for shortcuts, for example:
    • :* for all
    • :first for the first element on the corresponding axis
    • :last for the last element the corresponding axis
    • use (documentation keyword 'mlx:slice) to get the documentation of slice shortcuts documentations

  Examples:

  • take the all (:*) elements in first axis, second (2) element in second axis, [0, 2) elements in third axis:

    (let ((arr (reshape (arange 0 27) '(3 3 3))))
      (at arr :* 1 (~ 0 2)))
    

    array([[3, 4],
           [12, 13],
           [21, 22]], dtype=float32)
    

    this can also bewritten as:

    (let ((arr (reshape (arange 0 27) '(3 3 3))))
      (at arr :all :second 1/2))
    

    array([[3, 4],
           [12, 13],
           [21, 22]], dtype=float32)
    

    which means take all (:all) elements in first axis, second (:second) element in second axis, first half (1/2) in third axis.

    this is equal to calling MLX Python's API like:

    import mlx.core as mx
    print(mx.arange(0, 27).reshape((3, 3, 3))[:,1,0:2])
    

    array([[3, 4],
           [12, 13],
           [21, 22]], dtype=int32)
    

  • take all element in the first axis, the 0, 2, 3 th elements on the second axis:

    (let ((arr (reshape (arange 0 20) '(2 10))))
      (at arr :* '(0 2 3)))
    

    array([[0, 2, 3],
           [10, 12, 13]], dtype=float32)
    

    this is equal to calling MLX Python's API like:

    import mlx.core as mx
    print(mx.arange(0, 20).reshape((2, 10))[:,[0, 2, 3]])
    

    array([[0, 2, 3],
           [10, 12, 13]], dtype=int32)
    

  Dev Note: You can use defmlx-slice to define alias of the slice shortcuts. For example, the shortcuts of :all can be defined as:

  (defmlx-slice :all (shape)
    "Slice for all SHAPE. "
    (~ 0 shape 1))
  

  The documentation of mlx slice can be show by:

  (documentation :* 'at)
  

  Get all elements of axis in mlx-array.
  Return (~ 0 SHAPE 1).
  

MLX-CL overwrites a few of Common Lisp's methods (cl:+, cl:-, cl:*, cl:/, …) as generic functions. So if you don't worry about some speed lost, you can do

(+ 1 (* 2 3) (/ 10 5))

9 (4 bits, #x9, #o11, #b1001)

as if you are using cl:+, cl:-, cl:*, cl:/ (other functions are the same).

For those functions that are not supported in normal common lisp functions:

(+ 2 '(3 4 5))

array([5, 6, 7], dtype=float32)

they would be convert into mlx-array automatically. Use lisp<- to force convert mlx-array as lisp value.

(defun gauss-kernel (sigma &optional m
                     &aux
                       (m-min (1+ (* 2 (ceiling (* 3 sigma)))))
                       (m-val (the (or null (integer 0)) (or m m-min))))
  "Return a Gauss kernel matrix.

Definition:
   gauss(x, y) = exp(- (x^2 + y^2) / (2 * sigma^2)) / (2 * pi * sigma^2)
"
  (declare (type (real 0) sigma)
           (type (or null integer) m))
  (when (lisp<- (< m-val m-min))
    (warn "Given m=~A is lower than m_min=~A. " m-val m-min))
  (let ((half (/ (1- m-val) 2)))
    (destructuring-bind (x y)
        (meshgrid (arange (- half) (1+ half))
                  (arange (- half) (1+ half)))
      (let ((ker (exp (- (/ (+ (square x) (square y))
                            (* 2 (square sigma)))))))
        (/ ker (sum ker))))))

(gauss-kernel 0.3)

array([[1.47169e-05, 0.00380683, 1.47169e-05],
       [0.00380683, 0.984714, 0.00380683],
       [1.47169e-05, 0.00380683, 1.47169e-05]], dtype=float32)