Numcl

This is a Numpy clone in Common Lisp. At the moment the library is written in pure Common Lisp, focusing more on correctness and usefulness, not speed.

• NUMCL is currently available in Quicklisp.
• ./example.lisp contains a script that you can explore the functions already implemented in NUMCL.
• Find the full documentation at: https://numcl.github.io/numcl/
• Check the latest benchmark result against numpy in https://github.com/numcl/numcl-benchmarks/ .

NEWS

• 2020/2/26 version 0.2.0 is released!
• 2020/2/29 matmul* : multi-argument version of matmul is added. It optimizes the multiplication order in order to reduce the runtime / memory.
• 2020/3/30 Refactored the type inference framework using float infiny / NaNs.
• 2020/6/29 Minor incompatibility: LOG, LOG2 always return real arrays. Use LOGC instead for the original behavior.

Quick tutorial

In order to guarantee the speed and to simplify the implementation, the arrays given to numcl functions must satisfy the following two conditions:

• It is a specialized array. Things of type (array single-float), (array (unsigned-byte 16)) etc.
• It is an array displaced to a simple 1D specialized array. ”Simple array” means a non-displaced, non-adjustable array without fill pointer.

This means you cannot directly feed the arrays such as #2A((0.0 1.0) (2.0 3.0)), which is an array of type (simple-array T).

There are two ways to create an array similar to what you have and is compatible to numcl:

• (reshape (arange 4.0) '(2 2))
• (asarray #2A((0.0 1.0) (2.0 3.0)))
  • or (asarray '((0.0 1.0) (2.0 3.0)))
  • or (asarray '(#(0.0 1.0) #(2.0 3.0))).
• (let ((a (zeros '(2 2) :type 'single-float))) (dotimes (i 2) (dotimes (j 2) (setf (aref a i j) ...)))).

The names and the parameters of numcl functions mostly (rather strictly) follows the numpy counterpart. There are even numpy names, such as dtype, which are just aliases for array-element-type.

Goals

• Closely follow the numpy API, but still make it lispy.
  • Delegate the documentation effort to Numpy community.
• Replace the Common Lisp array interface.
  • We do not deviate from the traditional symbols/idioms in Common Lisp unless necessary. Therefore we provide symbols that conflicts the Common Lisp symbol. Math functions become aliases to the original CL functions when the inputs are not arrays.
  • See doc/DETAILS.org#packages .

Features/Contracts

• APIs are provided as functions, not macros.
  • It is a design flaw otherwise.
  • This does not mean the API is functional — we use procedural code.
• Still, zero overhead.
  • The APIs are simply the wrappers over simple functions and designed to be fully inlined.
  • Optimization will be done on the compiler side, not by macros.
• Operations are type-correct.
  • They always return arrays of the most specific array-element-type. For example,
  • (zeros 5) returns a bit vector.
  • (asarray ‘(1 2 3)) returns an (unsigned-byte 2) vector.
  • See doc/DETAILS.org#types .
• NUMCL Arrays are CL arrays.
  • As this library aims to extend Common Lisp (not to replace part of it) in a compatible way, we do not introduce custom structures/classes for representing an array.
  • See doc/DETAILS.org#representation .

Dependencies

This library is at least tested on implementation listed below (note: I am lazy to update the version list below, but I regularly use it on much newer versions and never encountered a problem. As of writing, it works on 2.0.5.) :

• SBCL 1.4.12 on X86-64 Linux 4.4.0-141-generic (author’s environment)
• SBCL 1.5.1 on X86-64 Linux 4.4.0-141-generic (author’s environment)
• SBCL 2.0.1 on X86-64 Ubuntu 16.04.6 LTS Linux 4.15.0-1028-gcp
• ccl-1.11.5 on X86-64 Ubuntu 16.04.6 LTS Linux 4.15.0-1028-gcp
• SBCL 2.0.1 on X86-64 Mac OS X 10.13.6
• ccl-1.11.5 on X86-64 Mac OS X 10.13.6
• SBCL 2.0.0 on X86-64 Windows Server, version 1809
• SBCL 2.0.0 on Arm64 Ubuntu 16.04.6 LTS Linux 5.3.0-19-generic
• SBCL 1.5.8 on ppc64le Ubuntu 16.04.6 LTS Linux 5.0.0-37-generic

Dependency graph:

Author, License, Copyright

Masataro Asai (guicho2.71828@gmail.com)

Licensed under LGPL v3.

Copyright (c) 2019 IBM Corporation