Numpy clone in Common Lisp, using MAGICL/LLA/MGL-MAT as the backend (in the future)

numcl

* Numcl [[https://travis-ci.org/numcl/numcl][https://travis-ci.org/numcl/numcl.svg?branch=master]]

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/ .

[[https://asciinema.org/a/245792][https://asciinema.org/a/245792.svg]]

** 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.
  "[[http://www.lispworks.com/documentation/HyperSpec/Body/t_smp_ar.htm][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][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][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][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:

[[./numcl.png]]

** Author, License, Copyright

Masataro Asai (guicho2.71828@gmail.com)

Licensed under LGPL v3.

Copyright (c) 2019 IBM Corporation




numcl

Upstream URL

Author

License

numcl

Version:

License:

Authors:

Dependencies:

numcl.test

License:

Authors:

Dependencies:

Dependencies (12)

Dependents (1)