# The numcl Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The numcl Reference Manual

This is the numcl Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed Jun 15 05:26:03 2022 GMT+0.

## 1 Introduction

```* 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.
+ 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]]

Masataro Asai (guicho2.71828@gmail.com)

```

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 numcl

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

Author

Masataro Asai

Contact

LGPL

Version

0.2.0

Dependencies
• trivia (system).
• alexandria (system).
• iterate (system).
• type-r (system).
• constantfold (system).
• lisp-namespace (system).
• cl-randist (system).
• float-features (system).
• function-cache (system).
• specialized-function (system).
• gtype (system).
Source
Child Component

src (module).

Next: , Previous: , Up: The numcl Reference Manual   [Contents][Index]

## 3 Modules

Modules are listed depth-first from the system components tree.

Previous: , Up: Modules   [Contents][Index]

Source
Parent Component

numcl (system).

Child Components

## 4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 4.1 Lisp

Next: , Previous: , Up: Lisp   [Contents][Index]

Source
Parent Component

numcl (system).

ASDF Systems

Source
Parent Component

src (module).

Packages

#### 4.1.3 numcl/src/0specialops.lisp

Dependency

0package.lisp (file).

Source
Parent Component

src (module).

Internals

#### 4.1.4 numcl/src/1version.lisp

Dependency

0specialops.lisp (file).

Source
Parent Component

src (module).

Public Interface

numcl-version (function).

Internals

make-version-string (function).

#### 4.1.5 numcl/src/1constantfolded.lisp

Dependency

1version.lisp (file).

Source
Parent Component

src (module).

Internals

#### 4.1.6 numcl/src/1constants.lisp

Dependency

1constantfolded.lisp (file).

Source
Parent Component

src (module).

Internals

#### 4.1.7 numcl/src/1docstrings.lisp

Dependency

1constants.lisp (file).

Source
Parent Component

src (module).

Internals

#### 4.1.8 numcl/src/1instantiate.lisp

Dependency

1docstrings.lisp (file).

Source
Parent Component

src (module).

Internals

%make-array (function).

#### 4.1.9 numcl/src/1type.lisp

Dependency

1instantiate.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.10 numcl/src/1util.lisp

Dependency

1type.lisp (file).

Source
Parent Component

src (module).

Internals

#### 4.1.11 numcl/src/2alias.lisp

Dependency

1util.lisp (file).

Source
Parent Component

src (module).

Public Interface

#### 4.1.12 numcl/src/2aref.lisp

Dependency

2alias.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.13 numcl/src/2typeinfer.lisp

Dependency

2aref.lisp (file).

Source
Parent Component

src (module).

Internals

#### 4.1.14 numcl/src/3arange.lisp

Dependency

2typeinfer.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.15 numcl/src/3array.lisp

Dependency

3arange.lisp (file).

Source
Parent Component

src (module).

Public Interface

asarray (function).

Internals

#### 4.1.16 numcl/src/3copy.lisp

Dependency

3array.lisp (file).

Source
Parent Component

src (module).

Public Interface

#### 4.1.17 numcl/src/3einsum.lisp

Dependency

3copy.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.18 numcl/src/3zeros.lisp

Dependency

3einsum.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

+zeros-doc+ (special variable).

#### 4.1.19 numcl/src/4concatenate.lisp

Dependency

3zeros.lisp (file).

Source
Parent Component

src (module).

Public Interface

#### 4.1.20 numcl/src/4einsum-backends/common-lisp.lisp

Dependency

4concatenate.lisp (file).

Source
Parent Component

src (module).

Internals

Dependency
Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.22 numcl/src/4linear-algebra3.lisp

Dependency

4linear-algebra2.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.23 numcl/src/5numeric.lisp

Dependency

4linear-algebra3.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

#### 4.1.24 numcl/src/5random.lisp

Dependency

5numeric.lisp (file).

Source
Parent Component

src (module).

Public Interface

#### 4.1.25 numcl/src/5reduce.lisp

Dependency

5random.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

#### 4.1.26 numcl/src/5where.lisp

Dependency

5reduce.lisp (file).

Source
Parent Component

src (module).

Public Interface
Internals

%array-index-from-row-major-index/vector (function).

## 5 Packages

Packages are listed by definition order.

Next: , Previous: , Up: Packages   [Contents][Index]

### 5.1 numcl.impl

Internal package for implementing numcl.

Source
Use List
• alexandria.
• common-lisp.
• constantfold.
• gtype.
• iterate.
• numcl.exported.
• specialized-function.
• trivia.level2.
• type-r.
Internals

Next: , Previous: , Up: Packages   [Contents][Index]

### 5.2 numcl

NUMCL defines several symbols which have the same name as the corresponding CL symbols. We call them **conflicting symbols**. To avoid the confusion in the code base, we use 3 packages: NUMCL.EXPORTED, NUMCL.IMPL, NUMCL.

This package replaces COMMON-LISP package by shadowing-import symbols from NUMCL.EXPORTED on top of COMMON-LISP package.

Source
Use List

Previous: , Up: Packages   [Contents][Index]

### 5.3 numcl.exported

External package for storing the exported symbols.

Source
Used By List
Public Interface

## 6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 6.1 Public Interface

#### 6.1.1 Symbol macros

Symbol Macro: *
Package
Source
Symbol Macro: **
Package
Source
Symbol Macro: ***
Package
Source
Symbol Macro: +
Package
Source
Symbol Macro: ++
Package
Source
Symbol Macro: +++
Package
Source
Symbol Macro: /
Package
Source
Symbol Macro: //
Package
Source
Symbol Macro: ///
Package
Source

#### 6.1.2 Compiler macros

Compiler Macro: arange (&rest args)
Package
Source
Compiler Macro: broadcast (function x y &key type atomic)

For binary functions

Package
Source
Compiler Macro: diag (a &optional result)

Return the diagonal element of a matrix as a vector

Package
Source
Compiler Macro: einsum (subscripts &rest args)
Package
Source
Compiler Macro: eye (n &key m k type)

Returns a matrix whose k-th diagnonal filled with 1.
N,M specifies the shape of the return array. K will adjust the sub-diagonal – positive K moves it upward.

Package
Source
Compiler Macro: inner (a b &optional result)

Inner product of two vectors.

Package
Source
Compiler Macro: kron (a b &optional result)

Compute the kronecker product of two vectors.

Package
Source
Compiler Macro: map-array-into (result-sequence function &rest sequences)
Package
Source
Compiler Macro: matmul (a b &optional result)

Matrix product of two arrays.

Package
Source
Compiler Macro: matmul* (&rest args)
Package
Source
Compiler Macro: outer (a b &optional result)

Compute the outer product of two vectors.

Package
Source
Compiler Macro: transpose (matrix &optional result)

Reverses the axes of an array.

Package
Source
Compiler Macro: tri (n &key m k type)

Returns a triangle matrix whose lower diagnonal (including the diagonal) filled with 1.
N,M specifies the shape of the return array. K will adjust the sub-diagonal – positive K fills more 1s.

Package
Source
Compiler Macro: tril (matrix &optional k)

Returns the copy of matrix with elements above the k-th diagonal zeroed. Positive K fills less 0s.

Package
Source
Compiler Macro: triu (matrix &optional k)

Returns the copy of matrix with elements below the k-th diagonal zeroed. Positive K fills more 0s.

Package
Source
Compiler Macro: vander (v &key n increasing)

Returns a matrix where M[i,j] == V[i]^(N-j) when increasing is false (default), and M[i,j] == V[i]^j when increasing is true.

Package
Source
Compiler Macro: vdot (a b &optional result)

Dot product of two vectors. For complex values, the first value is conjugated.

Package
Source

#### 6.1.3 Ordinary functions

Function: * (&rest args)
Package
Source
Function: + (&rest args)
Package
Source
Function: - (first &rest args)
Package
Source
Function: / (first &rest args)
Package
Source
Function: /= (x y &rest more)
Package
Source
Function: 1+ (array)
Package
Source
Function: 1- (array)
Package
Source
Function: < (x y &rest more)
Package
Source
Function: <= (x y &rest more)
Package
Source
Function: = (x y &rest more)
Package
Source
Function: > (x y &rest more)
Package
Source
Function: >= (x y &rest more)
Package
Source
Function: abs (x)
Package
Source
Function: acos (x)
Package
Source
Function: acosh (x)
Package
Source
Function: amax (array &rest args &key axes type)
Package
Source
Function: amin (array &rest args &key axes type)
Package
Source
Function: arange (&rest args)

Arange’s argument signature is irregular, following the API of numpy. The interpretation of its arguments depends on the number of arguments.

(arange stop &key type)
(arange start stop &key type)
(arange start stop step &key type)

Don’t worry, we provide a compiler-macro to avoid the runtime dispatch.

Package
Source
Function: aref (array &rest subscripts)

An extended ‘aref‘ that accepts ranges as lists, similar to numpy’s array access. For a 3D array x,

* range

“‘
x[1:5,2,3] = (aref x ’(1 5) 2 3)
x[2,1:5,3] = (aref x 2 ’(1 5) 3)
x[2,1:2:5,3] = (aref x 2 ’(1 2 5) 3)
x[2,1:,3] = (aref x 2 ’(1 t) 3)
x[2,:1,3] = (aref x 2 ’(t 1) 3)
x[2,:,3] = (aref x 2 ’(t t) 3)
x[2,:,3] = (aref x 2 t 3)
“‘

* insufficient axis

“‘commonlisp
(aref x ’(1 5)) == (aref x ’(1 5) t t)
(aref x 2 ’(1 5)) == (aref x 2 ’(1 5) t)
“‘

* newaxis

“‘commonlisp
(aref x ’(1 2 5) nil 2 3)
“‘

* ellipsis

“‘commonlisp
(aref x ’- 2) = (aref x t t 2) = x[...,2]
(aref x 2 ’-) = (aref x 2 t t) = x[2,...]
(aref x 2 ’- 3) = (aref x 2 t 3) = x[2,...,3]
(aref x 2 3 ’-) = (aref x 2 3 t) = x[2,3,...]
“‘

Package
Source
Function: (setf aref) (array &rest subscripts)
Package
Source
Function: argwhere (array fn)

Returns a list of the multidimentional indices of the elements which satisfies the predicate FN. Note that the list elements are the multidimentional indices, even for a single-dimensional array.

Package
Source
Function: array-index-from-row-major-index (array row-major-index)

Takes a multidimentional array and a row-major-index. Returns a list containing the normal index.

Package
Source
Function: asarray (contents &key type)

Note: ASARRAY is *SLOW* as it recurses into the substructures.

Copy ‘CONTENTS‘ to a new array.
When ‘CONTENTS‘ is a multidimentional array, its elements are copied to a new array that guarantees the NUMCL assumption. When ‘CONTENTS‘ is a nested sequence, it is traversed up to the depth that guarantees the sane shape for an array. When elements are copied, it is coerced to TYPE.
When TYPE is not given, it is replaced with the float-contagion type deduced from the elements of ‘CONTENTS‘.
It may return a 0-dimensional array with ‘CONTENTS‘ being the only element.

For example:

“‘lisp
;; a vector of two lists.
(asarray ’((1) (1 2))) -> #((1) (1 2))
;; a 2D array of 4 lists.
(asarray ’(((1) (1 2)) ((3) (3 4)))) -> #2A(((1) (1 2)) ((3) (3 4)))

(asarray ’((1 2) (3 4))) -> #2A((1 2) (3 4))
(asarray #(#(1 2) #(3 4))) -> #2A((1 2) (3 4))
(asarray #((1 2) (3 4))) -> #2A((1 2) (3 4))
“‘

However, this behavior may not be ideal because the resulting shape could be affected by the lengths of the strings.

“‘lisp
(asarray #(#(1 2) #(3 4))) -> #2A((1 2) (3 4))
(asarray #(#(1 2) #(3 4 5))) -> #(#(1 2) #(3 4 5))

(asarray #("aa" "aa")) -> #2A((#a #a) (#a #a))
(asarray #("aa" "aaa")) -> #("aa" "aaa")
“‘

As a remedy to this problem, we allow TYPE to be a specifier for vector subtypes. Providing such a type specifier will keep the leaf objects (e.g. strings) from split into individual elements.
We don’t allow it to be a multidimentional array [at the moment.]

“‘lisp
(asarray #(#(1 2) #(3 4)) :type ’(array fixnum (*))) -> #(#(1 2) #(3 4))
(asarray #(#(1 2) #(3 4 5)) :type ’(array fixnum (*))) -> #(#(1 2) #(3 4 5))

(asarray #("aa" "aa") :type ’string) -> #("aa" "aa")
(asarray #("aa" "aaa") :type ’string) -> #("aa" "aaa")

(asarray ’((1 2) (3 4)) :type ’(array fixnum (* *))) -> error
“‘

Package
Source
Function: asin (x)
Package
Source
Function: asinh (x)
Package
Source
Function: astype (array type)
Package
Source
Function: atan (x)
Package
Source
Function: atanh (x)
Package
Source
Function: avg (array &key axes)
Package
Source
Function: bernoulli (p &optional shape)

Returns a bit array whose elements are 1 with probability P

Package
Source
Function: bernoulli-like (a)
Package
Source
Function: beta (a b &optional shape type)
Package
Source
Function: binomial (n p &optional shape)
Package
Source
Function: broadcast (function x y &key type atomic)

For binary functions

Package
Source
Function: ceiling (number &optional divisor)
Package
Source
Function: cis (x)
Package
Source
Function: clip (array min max)
Package
Source
Function: concatenate (arrays &key axis out)
Package
Source
Function: conjugate (x)
Package
Source
Function: copy (array)
Package
Source
Function: cos (x)
Package
Source
Function: cosh (x)
Package
Source
Function: denominator (x)
Package
Source
Function: diag (a &optional result)

Return the diagonal element of a matrix as a vector

Package
Source
Function: dtype (array)
Package
Source
Function: einsum (subscripts &rest args)

Note: Broadcasting with ‘EINSUM‘ is experimental.

Performs Einstein’s summation.
The SUBSCRIPT specification is significantly extended from that of Numpy
and can be seens as a full-brown DSL for array operations.

SUBSCRIPTS is a sequence of the form ‘(<ISPEC>+ [-> <TRANSFORM>*] [-> <OSPEC>*] [-> <IOPTION>*] [-> <OOPTION>*])‘.
The remaining arguments ARGS contain the input arrays and optionally the output arrays.

Inputs are interpreted in the following rule, depending on the number of arrows.

“‘commonlisp
(<ISPEC>+)
(<ISPEC>+ -> <OSPEC>*)
(<ISPEC>+ -> <TRANSFORM>* -> <OSPEC>*)
(<ISPEC>+ -> <TRANSFORM>* -> <OSPEC>* -> <IOPTION>*)
(<ISPEC>+ -> <TRANSFORM>* -> <OSPEC>* -> <IOPTION>* -> <OOPTION>*)
“‘

# SPEC

The first set of SPECs specifies the input subscripts,
and the second set of SPECs specifies the output subscripts.
Unlike Numpy, there can be multiple output subscripts:
It can performs multiple operations in the same loop, then return multiple values.
The symbol ‘->‘ can be a string and can belong to any package because it is compared by ‘STRING=‘.

Each SPEC is an string designator, such as a symbol IJK or a string "IJK",
where each character is considered as an index.
Broadcasting can be specified by a hyphen.
It signals a type-error when it contains any non-alpha char except hyphens (-).
Note that a symbol NIL is interpreted as an empty list rather than N, I and L.
Once broadcasting is used in one input, it must be used in all inputs/outputs.

Alternatively, each SPEC can be a list that contains a list of symbols.
For example, ‘((i j) (j k) -> (i k))‘ and ‘(ij jk -> ik)‘ are equivalent.

When -> and the output SPECs are omitted, a single output is assumed and its spec is
a union of the input specs.
For example, ‘(ij jk)‘ is equivalent to ‘(ij jk -> ijk)‘.
Note that ‘(ij jk)‘ and ‘(ij jk ->)‘ have the different meanings:
The latter sums up all elements.

# TRANSFORM

TRANSFORM is a list of element-wise operations.
The number of TRANSFORM should correspond to the number of outputs.
In each TRANSFORM, the elements in the input arrays can be referenced by \$N, where N is a 1-indexed number.
Similarly the output array can be referred to by @N.

+ Example: ‘(ij ik -> (+ @1 (* \$1 \$2)) -> ik)‘ is equivalent to ‘(ij ik -> ik)‘ (a GEMM).
+ Example: ‘(i -> (sin \$1) -> i)‘ is equivalent to mapping a sin function to an array.

By default, TRANSFORM is ‘(+ @1 (* \$1 ... \$N))‘ for N inputs, which is equivalent to Einstein’s summation.

# OPTION

Each OPTION is a list of iteration specifiers.
Iteration specifier is a form ‘(index &key (start 0) (end -1) (step 1))‘.
‘START‘ and ‘END‘ are the forms specifying the interval designator of the loop range, which supersedes the default full-width loop. ‘STEP‘ is a form specifying the increment of the index.
‘INDEX‘ is a symbol which should match one of the subscripts used in one of the ‘SPEC‘.

For example, you can specify

“‘commonlisp
(einsum ’(ij jk -> (+ @1 (* \$1 \$2)) -> ik -> ((j :step 2)) ((j :step 3)))
(ones ’(5 10))
(ones ’(15 5)))
“‘

to suggest that
the index ‘j‘ for the first array should have a stride of 2,
and the index ‘j‘ for the second array should have a stride of 3.

This is fairly complex, but we hope to provide the maximum flexibility.

# ARGS

The shape of each input array should unify against the corresponding input spec. For example,
with a spec ‘IJI‘, the input array should be of rank 3 as well as
the 1st and the 3rd dimension of the input array should be the same.
Note that this is affected by ‘OPTIONS‘ — when specified,
it uses the number of iteration instead of the size of the dimension.

The shape of each output array is determined by the corresponding output spec.
For example, if ‘SUBSCRIPTS‘ is ‘(ij jk -> ik)‘
and the input arrays are NxM and MxL matrices, the output has a shape NxL.

If the output arrays are provided, their shapes and types are also checked against the
corresponding output spec. The types should match the result of the numerical
operations on the elements of the input arrays.

The outputs are calculated in the following rule.

+ The output array types are calculated based on the ‘TRANSFORM‘, and
the shapes are calcurated based on the ‘SPEC‘ and the input arrays.
+ The output arrays are allocated and initialized by zeros.
+ Einsum nests one loop for each index in the input specs.
For example, ‘(ij jk -> ik)‘ results in a triple loop.
+ In the innermost loop, each array element is bound to ‘\$1..\$N‘ / ‘@1..@N‘.
+ For each ‘@i‘, ‘i‘-th transform is evaluated and assigned to ‘@i‘.

+ If the same index appears multiple times in a single spec,
they share the same value in each iteration.
For example, ‘(ii -> i)‘ returns the diagonal elements of the matrix.

When TRANSFORMs are missing, it follows naturally from the default ‘TRANSFORM‘ values that

+ When an index used in the input spec is missing in the output spec,
the axis is aggregated over the iteration by summation.
+ If the same index appears across the different input specs,
the element values from the multiple input arrays are aggregated by multiplication.
For example, ‘(ij jk -> ik)‘ will perform
‘(setf (aref a2 i k) (* (aref a0 i j) (aref a1 j k)))‘
when a0, a1 are the input arrays and a2 is the output array.

For example, ‘(einsum ’(ij jk) a b)‘ is equivalent to:

“‘commonlisp
(dotimes (i <max> <output>)
(dotimes (j <max>)
(dotimes (k <max>)
(setf (aref <output> i j k) (* (aref a i j) (aref b j k))))))
“‘

# Performance

If ‘SUBSCRIPTS‘ is a constant, the compiler macro
builds an iterator function and make them inlined. Otherwise,
a new function is made in each call to einsum, resulting in a large bottleneck.
(It could be memoized in the future.)

The nesting order of the loops are automatically decided based on the specs.
The order affects the memory access pattern and therefore the performance due to
the access locality. For example, when writing a GEMM which accesses three matrices
by ‘(setf (aref output i j) (* (aref a i k) (aref b k j)))‘,
it is well known that ikj-loop is the fastest among other loops, e.g. ijk-loop.
EINSUM reorders the indices so that it maximizes the cache locality.

Package
Source
Function: empty (shape &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: empty-like (array &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: exp (x)
Package
Source
Function: expand-dims (a axes)

axes: an int or a list of ints

Package
Source
Function: exponential (scale &optional shape type)
Package
Source
Function: expt (base power)
Package
Source
Function: eye (n &key m k type)

Returns a matrix whose k-th diagnonal filled with 1.
N,M specifies the shape of the return array. K will adjust the sub-diagonal – positive K moves it upward.

Package
Source
Function: f (dfnum dfden &optional shape type)
Package
Source
Function: fceiling (number &optional divisor)
Package
Source
Function: ffloor (number &optional divisor)
Package
Source
Function: flatten (a)
Package
Source
Function: floor (number &optional divisor)
Package
Source
Function: fround (number &optional divisor)
Package
Source
Function: ftruncate (number &optional divisor)
Package
Source
Function: full (shape value &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: full-like (array value &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: gamma (k &optional theta shape type)
Package
Source
Function: histogram (array &key low high split)

Returns a fixnum vector representing a histogram of values. The interval between LOW and HIGH are split by STEP value. All values less than LOW are put in the 0-th bucket;
All values greater than equal to HIGH are put in the last bucket.

Package
Source
Function: imagpart (x)
Package
Source
Function: inner (a b &optional result)

Inner product of two vectors.

Package
Source
Function: integer-length (x)
Package
Source
Function: isqrt (x)
Package
Source
Function: kron (a b &optional result)

Compute the kronecker product of two vectors.

Package
Source
Function: length (array)
Package
Source
Function: linspace (start stop &key num endpoint type)
Package
Source
Function: log (x)

Logarithmic function.
Unlike Common Lisp LOG, it assumes that the input is a positive real, in favor of efficiency. Another reason is that most Common Lisp implementations do not have specialized arrays for positive-only / negative-only floats, thus the runtime type inference cannot deduce whether the resulting array element type have to be a complex or a real.

Package
Source
Function: log2 (x)

Logarithm of base 2.

Package
Source
Function: logand (&rest args)
Package
Source
Function: logandc1 (&rest args)
Package
Source
Function: logandc2 (&rest args)
Package
Source
Function: logc (x)

Logarithmic function.
This function behaves exactly like Common Lisp LOG.
Unless it can be proven from the input array element type, such as the input being
a specialized array of unsigned-int, it takes a conservative approach, i.e., it returns arrays specialized to the complex numbers.

Package
Source
Function: logcount (x)
Package
Source
Function: logeqv (&rest args)
Package
Source
Function: logior (&rest args)
Package
Source
Function: lognand (&rest args)
Package
Source
Function: lognor (&rest args)
Package
Source
Function: lognot (x)
Package
Source
Function: logorc1 (&rest args)
Package
Source
Function: logorc2 (&rest args)
Package
Source
Function: logxor (&rest args)
Package
Source
Function: map (result-type function &rest sequences)
Package
Source
Function: map-array (function &rest sequences)
Package
Source
Function: map-array-into (result-sequence function &rest sequences)
Package
Source
Function: map-into (result-sequence function &rest sequences)
Package
Source
Function: matmul (a b &optional result)

Matrix product of two arrays.

Package
Source
Function: matmul* (&rest args)

Takes an arbitrary number of matrices and performs multiplication, optimizing the order using the shape information and the associativity to minimize the size of the intermediate matrix.

Package
Source
Function: max (&rest args)
Package
Source
Function: mean (array &key axes)
Package
Source
Function: min (&rest args)
Package
Source
Function: mod (number &optional divisor)
Package
Source
Function: multinomial (n pvals &optional shape)

pvals is a sequence of probabilities summing up to 1.

Package
Source
Function: negative-binomial (n p &optional shape)
Package
Source
Function: nonzero (array)

collect multidimentional indices where the element is nonzero

Package
Source
Function: normal (&optional mean var shape type)
Package
Source
Function: numcl-array-p (array)

Returns true when ARRAY satisfies the NUMCL assumption, that is, an array displaced to a non-displaced 1D array.

Package
Source
Function: numcl-version ()

Returns a string that represents the version of NUMCL currently installed.

Package
Source
Function: numerator (x)
Package
Source
Function: ones (shape &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: ones-like (array &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: outer (a b &optional result)

Compute the outer product of two vectors.

Package
Source
Function: phase (x)
Package
Source
Function: poisson (&optional lambda shape type)
Package
Source
Function: prod (array &rest args &key axes type)
Package
Source
Function: rank (array)
Package
Source
Function: realpart (x)
Package
Source
Function: reduce-array (fn array &key axes type initial-element)
Package
Source
Function: rem (number &optional divisor)
Package
Source
Function: reshape (a shape)

Reshape the array while sharing the backing 1D array.
-1 implies that the axis size is deduced from the other axes. At most one axis is allowed to be -1.
T implies that the axis size is preserved. It can be used as many times, but only at the right/leftmost axes.

Example of reshaping (3 8 5):

valid:

(6 -1 10) = (6 2 10)
(t 2 2 2 t) = (3 2 2 2 5)
(3 t t) = (3 8 5)
(2 -1 2 2 t) = (2 3 2 2 5)

invalid:

(2 t 2 2 t)

Package
Source
Function: round (number &optional divisor)
Package
Source
Function: shape (array)
Package
Source
Function: shuffle (array-or-sequence &key start end)

This code extends alexandria:shuffle.
It additionally accepts arrays and shuffles the elements according to the first axis, viewing the remaining axes as one "element".

Original documentation:

Returns a random permutation of SEQUENCE bounded by START and END.
Original sequence may be destructively modified, and (if it contains
CONS or lists themselv) share storage with the original one.
Signals an error if SEQUENCE is not a proper sequence.

Package
Source
Function: signum (x)
Package
Source
Function: sin (x)
Package
Source
Function: sinh (x)
Package
Source
Function: size (array)
Package
Source
Function: sqrt (x)
Package
Source
Function: square (x)

Square function f(x)= x * x.

Package
Source
Function: squeeze (a)
Package
Source
Function: stack (arrays &key axis out)
Package
Source
Function: standard-deviation (array &key axes)
Package
Source
Function: stdev (array &key axes)
Package
Source
Function: sum (array &rest args &key axes type)
Package
Source
Function: take (array indices)

Collect the elements using a list of multidimentional indices (in a format returned by WHERE).

Package
Source
Function: tan (x)
Package
Source
Function: tanh (x)
Package
Source
Function: to-simple-array (array)

Returns a simple array of the equivalent contents.

Package
Source
Function: transpose (matrix &optional result)

Reverses the axes of an array.

Package
Source
Function: tri (n &key m k type)

Returns a triangle matrix whose lower diagnonal (including the diagonal) filled with 1.
N,M specifies the shape of the return array. K will adjust the sub-diagonal – positive K fills more 1s.

Package
Source
Function: tril (matrix &optional k)

Returns the copy of matrix with elements above the k-th diagonal zeroed. Positive K fills less 0s.

Package
Source
Function: triu (matrix &optional k)

Returns the copy of matrix with elements below the k-th diagonal zeroed. Positive K fills more 0s.

Package
Source
Function: truncate (number &optional divisor)
Package
Source
Function: uniform (&optional low high shape type)
Package
Source
Function: unstack (array &key axis)
Package
Source
Function: vander (v &key n increasing)

Returns a matrix where M[i,j] == V[i]^(N-j) when increasing is false (default), and M[i,j] == V[i]^j when increasing is true.

Package
Source
Function: var (array &key axes)
Package
Source
Function: variance (array &key axes)
Package
Source
Function: vdot (a b &optional result)

Dot product of two vectors. For complex values, the first value is conjugated.

Package
Source
Function: where (array fn)

Returns a list of list of indices of the elements which satisfies the predicate FN. The first list contains the indices for the 1st dimension,
the second list contains the indices for the 2nd dimension, and so on.

Package
Source
Function: zeros (shape &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source
Function: zeros-like (array &key type)

Equivalent of the same function in numpy. Note the default ‘type‘ difference.

+ ‘empty‘ : does not explicitly fill the array. In an unsafe compiler setting, junk value may appear.
+ ‘full‘ : fill the array with a certain value.
+ ‘zeros‘, ‘ones‘ : fill the array with zeros / ones. ‘type‘ affects the actual value being filled.
+ ‘X-like‘ : similar to above functions, but takes another array and returns the array of the same shape.

Package
Source

#### 6.1.4 Generic functions

Generic Writer: (setf invalid-array-index-error-axis) (condition)
Package
Methods
Writer Method: (setf invalid-array-index-error-axis) ((condition invalid-array-index-error))
Source
Target Slot

axis.

Generic Writer: (setf invalid-array-index-error-shape) (condition)
Package
Methods
Writer Method: (setf invalid-array-index-error-shape) ((condition invalid-array-index-error))
Source
Target Slot
Generic Writer: (setf invalid-array-index-error-subscripts) (condition)
Package
Methods
Writer Method: (setf invalid-array-index-error-subscripts) ((condition invalid-array-index-error))
Source
Target Slot

Next: , Previous: , Up: Public Interface   [Contents][Index]

#### 6.1.5 Conditions

Condition: invalid-array-index-error
Package
Source
Direct superclasses

type-error.

Direct methods
Direct slots
Slot: shape
Initargs

:shape

Writers
Slot: axis
Package
Initargs

:axis

Writers
Slot: subscripts
Package
Initargs

:subscripts

Writers

Previous: , Up: Public Interface   [Contents][Index]

#### 6.1.6 Types

Type: numcl-array (&optional element-type dimensions)

Type specifier for the arrays satifying the NUMCL assumption, that is, an array displaced to a non-displaced 1D array.

Package
Source

### 6.2 Internals

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.1 Constants

Constant: *numcl-default-float-format*

The default format for numcl arrays. Bignums and ratios are coerced into this type during computation.

Package
Source
Constant: +quater+
Package
Source

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.2 Special variables

Special Variable: *compiler*
Package
Source
Special Variable: *inferer-doc-table*
Package
Source
Special Variable: *inferer-table*
Package
Source
Special Variable: *initialized-idxs*
Package
Source
Special Variable: *memoized-einsum-function-cache*
Package
Source
Special Variable: *used-evars*
Package
Source
Special Variable: +zeros-doc+
Package
Source

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.3 Symbol macros

Symbol Macro: %float%
Package
Source
Symbol Macro: *aref-documentation*
Package
Source
Symbol Macro: *asarray-documentation*
Package
Source
Symbol Macro: *einsum-documentation*
Package
Source

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.4 Macros

Macro: %when-function-is-global (&body body)

Internal use only! assumes a fixed set of variable names

Package
Source
Macro: compile-time-type-of (variable)
Package
Source
Macro: define-foldable-version (symbol)

This macro defines a constant-foldable variant of the standard functions, such
as list or a vector. The functions in 1constantfolded.lisp mainly consists of sequense functions.

Standard functions, e.g. list, require that a new object (a list) is created every time. However, there are many cases in numcl that it is preferable to constant-fold them
assuming that the result value is only used as a compile-time constant.

These are typically the functions that are declared flushable but not foldable in SBCL.
We do not include copier functions.

New functions are named with an additional C in the beginning. For example,
CLIST is a constant-foldable version of LIST.

We thank Baggers’ TAMEI library for the reference database.

Package
Source
Macro: define-simple-mapper (numcl-fn cl-fn &optional docstring)
Package
Source
Macro: do (bindings (end-test-form &body result-form) &body body)

A DO wrapper that recognizes DERIVE declaration.

Package
Source
Macro: do* (bindings (end-test-form &body result-form) &body body)

A DO* wrapper that recognizes DERIVE declaration.

Package
Source
Macro: in-current-package (&body body)

Bind *package* to the load-time-value of *package*.
Used frequently for controlling the default package for the reader.

Package
Source
Macro: inline-except-toplevel ((&key) &body defun-form)

Takes a DEFUN form, then return a PROGN containing two versions of the defun form:
One is the original form, and another, which have the same definition (arguments and body) but has the name prefixed with ‘inlinable-‘. This inlinable- version is declared inline. Furthermore, it defines the compiler-macro for the original function
which expands to the inlinable version when ‘*compile-file-pathanme*‘ is set in the compile time. This way it prevents inlining in the REPL.

This macro is important for certain functions (e.g. MATMUL) that contain delayed compilation using specialized-function, mainly EINSUM.
We want those functions to be inline-expanded (to expose EINSUM) which is later fused with other EINSUMs. However, when the function is used on the toplevel form (e.g. REPL)
without this macro, it always expands to EINSUM and thus always creates a new function table.

Package
Source
Macro: let (bindings &body body)

A LET wrapper that recognizes DERIVE declaration.

Package
Source
Macro: let* (bindings &body body)

A LET wrapper that recognizes DERIVE declaration.

Package
Source
Macro: locally (&body body)

A LET wrapper that recognizes DERIVE declaration.

Package
Source
Macro: printing (&body body)

debugging function – A progn that prints each form in the body

Package
Source
Macro: without-* (&body body)

Internal macro

Package
Source

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.5 Compiler macros

Compiler Macro: %arange-infer-type (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: %coerce (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: bind-to-float-type (&rest args)

Performs constant-folding for commutative and associative functions. Following optimization is performed:

(+ a 2 3 b 1) –> (+ (+ 2 3 1) a b) –> (+ 6 a b)

Package
Alias for

foldable-commutative-associative-fn.

Compiler Macro: cacons (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cappend (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-and (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-andc1 (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-andc2 (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-eqv (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-ior (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-nand (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-nor (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-not (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-orc1 (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-orc2 (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cbit-xor (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cconcatenate (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: ccons (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cintersection (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cldiff (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: clist (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: clist* (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmake-array (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmake-list (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmake-sequence (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmake-string (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmap (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmapcar (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cmaplist (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cpairlis (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: creduce (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cremove (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cremove-duplicates (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cremove-if (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cremove-if-not (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: creverse (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cset-difference (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cset-exclusive-or (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring-capitalize (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring-downcase (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring-left-trim (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring-right-trim (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring-trim (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cstring-upcase (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csublis (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubseq (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubst (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubst-if (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubst-if-not (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubstitute (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubstitute-if (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: csubstitute-if-not (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cunion (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: cvector (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: float-contagion (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: float-substitution (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: float-to-integer-p (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: intersection-to-float-type (&rest args)

Performs constant-folding for commutative and associative functions. Following optimization is performed:

(+ a 2 3 b 1) –> (+ (+ 2 3 1) a b) –> (+ 6 a b)

Package
Alias for

foldable-commutative-associative-fn.

Compiler Macro: most-negative-value (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: most-positive-value (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: one-value (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

Compiler Macro: union-to-float-type (&rest args)

Performs constant-folding for commutative and associative functions. Following optimization is performed:

(+ a 2 3 b 1) –> (+ (+ 2 3 1) a b) –> (+ 6 a b)

Package
Alias for

foldable-commutative-associative-fn.

Compiler Macro: zero-value (&rest args)

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package
Alias for

foldable-fn.

#### 6.2.6 Ordinary functions

Function: \$ (i)

Variable for the input array element

Package
Source
Function: %%arange (start stop step type)
Package
Source
Function: %%expand-decls (decl env)
Package
Source

Compares two cases of what previous thing returns and returns the best one.

Package
Source
Function: %arange (start stop step type)
Package
Source
Function: %arange-infer-type (start stop step)
Package
Source
Function: %aref (array subscripts)
Package
Source
Function: %array-index-from-row-major-index/vector (array row-major-index &optional result)

Takes a multidimentional array and a row-major-index. Returns a vector containing the normal index.

Package
Source
Function: %aset-fill (newvar array subscripts)
Package
Source
Function: %aset-replace (newvar shape array subscripts)
Package
Source
Function: %build-tree (dimensions)

Builds an order tree of multiplications, dynamically solving it for all ranges.

Package
Source
Function: %check-two-matrices (first second)

first and second are cons of a form (height width) in this case.
The function returns the dimensions of resulting thing and the number of multiplications requred. I work under assertion, that those matrices are actually multipliable => (= (cdr first) (car second)).

Package
Source
Function: %coerce (object type)

COERCE that additionally converts NUMBER into INTEGER by rounding, and NUMBER to (un/signed-byte N) by modular arithmetic.

Package
Source
Function: %dimension-step-size (spec array-index out-p)
Package
Source
Function: %displace-at (array i)

Displace to the i-th element subarray in the first axis

Package
Source
Function: %displace-range (array from to)

Displace to the subarray between FROM-th and TO-th element subarray in the first axis

Package
Source
Package
Source
Function: %einsum-early-binding (rest ev)
Package
Source
Function: %einsum-leaf (ev)
Package
Source
Function: %einsum-loop (iter-specs ev)
Package
Source
Function: %einsum-normalize-subscripts (subscripts)

Normalizes the input to the einsum.
It first ’explodes’ each spec into the list form.
It then generates the default output form, if missing.

It then translates the index symbols into a number
based on the order of appearance; This should make
the specs with the different symbols into the canonical form,
e.g. ‘(ij jk -> ik)‘ and ‘(ik kj -> ij)‘ both results in something equivalent to
‘((0 1) (1 2) -> (0 2))‘.

The subscripts are converted into numbers in order to cache the resulting compiled function when einsum is called with a dynamically generated subscript.

It then inserts the default transforms, if missing.

The value returned is a plist of :i-specs, :transforms, :o-specs.
For example, ‘(einsum-normalize-subscripts ’(ik kj -> ij))‘ returns

“‘lisp
(:i-specs ((0 1) (1 2))
:transforms ((+ @1 (* \$1 \$2)))
:o-specs ((0 2)))
“‘

Broadcasting can be specified by a hyphen. For example, ’(-k -k -> -k)
is equivalent to numpy’s ellipses ’...k,...k->...k’ .
In the returned list, indices corresponding to the broadcasted axes are -1.

Package
Source
Function: %einsum-static (iter-specs ev)
Package
Source
Function: %expand-decls (decls env)
Package
Source
Function: %index->matrix (operation indices matrices)

Tree of indexes -> tree of multiplications

Package
Source
Function: %interpret-type (form)
Package
Source
Function: %interval-/= (x y)
Package
Source
Function: %interval-< (x y)
Package
Source
Function: %interval-<= (x y)
Package
Source
Function: %interval-= (x y)
Package
Source
Function: %interval-> (x y)
Package
Source
Function: %interval->= (x y)
Package
Source
Package
Source
Function: %interval-ceiling (number divisor)
Package
Source
Function: %interval-div (number divisor)
Package
Source
Function: %interval-divlike (fn x y)
Package
Source
Function: %interval-fceiling (number divisor)
Package
Source
Function: %interval-ffloor (number divisor)
Package
Source
Function: %interval-floor (number divisor)
Package
Source
Function: %interval-fround (number divisor)
Package
Source
Function: %interval-ftruncate (number divisor)
Package
Source
Function: %interval-max (x y)
Package
Source
Function: %interval-min (x y)
Package
Source
Function: %interval-mul (x y)
Package
Source
Function: %interval-round (number divisor)
Package
Source
Function: %interval-sub (x y)
Package
Source
Function: %interval-truncate (number divisor)
Package
Source
Function: %log2 (x)
Package
Source
Function: %log2-inferer (x)
Package
Source
Function: %logr (x)
Package
Source
Function: %make-array (shape &key element-type displaced-to displaced-index-offset initial-element)

The base function for creating a new array satisfying NUMCL-ARRAY-P. (See also: Type NUMCL-ARRAY.)

This function instantiates a fresh 1D array and returns another array
displaced to it with the specified shape. The 1D array is returned as the
secondary value.

The justification for this scheme is that some implementations (esp. SBCL)
require an indirection for accessing the array element (e.g. through
array-header in SBCL) even for a simple multi-dimentional array and thus using a
displacing array has essentially no performance penalty over using a simple
multi-dimentional array.

We also ensure that the length of the base arrays are the multiples of 8.
This ensures that the program can safely iterate over that extended region
with a future support for SIMD operations in mind.

When DISPLACED-TO is given, it should be a numcl array
and the returned array is displaced to its 1D backing array
with the same offsets as the DISPLACED-TO.

When DISPLACED-INDEX-OFFSET is also given, the actual offset is
the specified offset plus the original offset in DISPLACED-TO.

When DISPLACED-TO and ELEMENT-TYPE are given, the upgraded-array-element-type of ELEMENT-TYPE should be TYPE= to the actual array element type of DISPLACED-TO.

When DISPLACED-TO is given and ELEMENT-TYPE is not given,
ELEMENT-TYPE is simply the actual array element type of DISPLACED-TO.

Package
Source
Function: %map-array-with-type (type function &rest sequences)
Package
Source
Function: %nested-coerce-and-insert (base-array contents newtype level)
Package
Source
Function: %normalize-subscript (subscript dim)

Returns a subscript object.

Package
Source
Function: %ok-to-use-fn-specialized (function env)
Package
Source
Function: %output-generator (o-specs o-avars i-specs i-avars transforms)
Package
Source
Package
Source
Function: %reduce-array-result-type (array fn)
Package
Source
Function: %reduce-lambda (rvar avar fnvar current-axis dims sum-axes loop-index sum-index)
Package
Source
Function: %square (x)
Package
Source
Function: %straight-forward-check (sizes)

Naive atomic multiplications check for comparison

Package
Source
Function: & (i)

Variable for the iteration count

Package
Source
Function: /=/2 (x y)
Package
Source
Function: /=/bit (x y)
Package
Source
Function: 1+-inferer (typespec)
Package
Source
Function: </2 (x y)
Package
Source
Function: </bit (x y)
Package
Source
Function: <=/2 (x y)
Package
Source
Function: <=/bit (x y)
Package
Source
Function: =/2 (x y)
Package
Source
Function: =/bit (x y)
Package
Source
Function: >/2 (x y)
Package
Source
Function: >/bit (x y)
Package
Source
Function: >=/2 (x y)
Package
Source
Function: >=/bit (x y)
Package
Source
Function: ? (i)

Variable for the iteration limit

Package
Source
Function: @ (i)

Variable for the output array element

Package
Source
Function: abs-inferer (x)
Package
Source
Function: acos-inferer (x)
Package
Source
Function: acosh-inferer (x)
Package
Source
Package
Source
Function: array-dimension* (array axes)

An extension of array-dimension that can handle multiple axes. — WIP

Package
Source
Function: asin-inferer (x)
Package
Source
Function: asinh-inferer (x)
Package
Source
Function: atan-inferer (x)
Package
Source
Function: atanh-inferer (x)
Package
Source
Function: base-array-p (array)

Returns true when ARRAY is a base array of numcl array.

Package
Source
Function: bind-to-float-type (&rest typespecs)

Returns the upper/lower bound of the number type specifiers.

Package
Source
Function: boolean-wrapper (x y more binary multiary)
Package
Source

Broadcasting the binary operation is allowed when
the axes in the right-aligned common subscripts of the arrays are same or either subscript is 1

Package
Source
Package
Source
Function: cacons (&rest args)
Package
Source
Package
Source
Function: cappend (&rest args)
Package
Source
Function: cbit-and (&rest args)
Package
Source
Function: cbit-andc1 (&rest args)
Package
Source
Function: cbit-andc2 (&rest args)
Package
Source
Function: cbit-eqv (&rest args)
Package
Source
Function: cbit-ior (&rest args)
Package
Source
Function: cbit-nand (&rest args)
Package
Source
Function: cbit-nor (&rest args)
Package
Source
Function: cbit-not (&rest args)
Package
Source
Function: cbit-orc1 (&rest args)
Package
Source
Function: cbit-orc2 (&rest args)
Package
Source
Function: cbit-xor (&rest args)
Package
Source
Function: cconcatenate (&rest args)
Package
Source
Function: ccons (&rest args)
Package
Source
Function: ceiling-inferer (x &optional y)
Package
Source
Function: cintersection (&rest args)
Package
Source
Function: cldiff (&rest args)
Package
Source
Function: clist (&rest args)
Package
Source
Function: clist* (&rest args)
Package
Source
Function: cmake-array (&rest args)
Package
Source
Function: cmake-list (&rest args)
Package
Source
Function: cmake-sequence (&rest args)
Package
Source
Function: cmake-string (&rest args)
Package
Source
Function: cmap (&rest args)
Package
Source
Function: cmapcar (&rest args)
Package
Source
Function: cmaplist (&rest args)
Package
Source
Function: complex-part-inferer (x)
Package
Source
Function: conjugate-inferer (x)
Package
Source
Function: copy-einsum-specs (instance)
Package
Source
Function: copy-sub (instance)
Package
Source
Function: cos-inferer (x)
Package
Source
Function: cosh-inferer (x)
Package
Source
Function: cpairlis (&rest args)
Package
Source
Function: creduce (&rest args)
Package
Source
Function: cremove (&rest args)
Package
Source
Function: cremove-duplicates (&rest args)
Package
Source
Function: cremove-if (&rest args)
Package
Source
Function: cremove-if-not (&rest args)
Package
Source
Function: creverse (&rest args)
Package
Source
Function: cset-difference (&rest args)
Package
Source
Function: cset-exclusive-or (&rest args)
Package
Source
Function: cstring (&rest args)
Package
Source
Function: cstring-capitalize (&rest args)
Package
Source
Function: cstring-downcase (&rest args)
Package
Source
Function: cstring-left-trim (&rest args)
Package
Source
Function: cstring-right-trim (&rest args)
Package
Source
Function: cstring-trim (&rest args)
Package
Source
Function: cstring-upcase (&rest args)
Package
Source
Function: csublis (&rest args)
Package
Source
Function: csubseq (&rest args)
Package
Source
Function: csubst (&rest args)
Package
Source
Function: csubst-if (&rest args)
Package
Source
Function: csubst-if-not (&rest args)
Package
Source
Function: csubstitute (&rest args)
Package
Source
Function: csubstitute-if (&rest args)
Package
Source
Function: csubstitute-if-not (&rest args)
Package
Source
Function: csubtypep (x y)
Package
Source
Function: cunion (&rest args)
Package
Source
Package
Source
Package
Source
Function: cvector (&rest args)
Package
Source
Function: derive-type-expander (variable type newform env)
Package
Source
Function: determine-array-spec (contents type)

Walk over the CONTENTS recursively and decides the output shape and the element type. When TYPE is non-nil, it overrides the type deduction.

Package
Source
Function: div-to-float-type (first &rest typespecs)
Package
Source
Function: einsum-lambda (einsum-specs)

Takes a normalized-subscripts and returns a lambda form that iterates over it.

Package
Source
Function: einsum-normalize-subscripts (subscripts)
Package
Source
Function: einsum-output-types (transforms i-evars o-evars &rest arrays)

Try to simulate the range for 10 iterations; Stop if it converges. Otherwise call float-substitution and simplify integers to fixnums.

Package
Source
Writer: (setf einsum-specs-i-options) (instance)
Package
Source
Target Slot
Writer: (setf einsum-specs-i-specs) (instance)
Package
Source
Target Slot
Writer: (setf einsum-specs-iter-specs) (instance)
Package
Source
Target Slot
Writer: (setf einsum-specs-o-options) (instance)
Package
Source
Target Slot
Writer: (setf einsum-specs-o-specs) (instance)
Package
Source
Target Slot
Function: einsum-specs-p (object)
Package
Source
Writer: (setf einsum-specs-transforms) (instance)
Package
Source
Target Slot
Function: ensure-singleton (array-or-number)
Package
Source
Function: exp-inferer (x)
Package
Source
Function: expt-inferer (base power)
Package
Source
Function: float-contagion (t1 t2 &key int-int-result)

Performs a float contagion.

It returns a type specifier that can be combined with intervals.
For example, when the contagion result is FIXNUM, it returns ’INTEGER instead.
Specifically, it returns one of ’integer, ’short-float, ... ’long-float, ’(complex integer), ’(complex short-float) ... ’(complex long-float) or nil (i.e. empty type).

The rule applied here is stricter than in CL.
All ratios are converted to *numcl-default-float-format*.
NUMCL is aware of BIGNUM, but never handles it.
When the result of numerical computation causes an overflow/underflow, it signals an error.

For the original float contagion rule, check out:

The optional key argument :int-int-result can alter the behavior when the both inputs are integers. This is useful for specifying the appropriate default behavior for rational functions
(e.g. +: integer, integer -> integer) and irrational functions (e.g. /: integer, integer -> float).

Package
Source
Function: float-substitution (t1 &key int-result)

Performs a float substitution.

For the original float substitution rule, check out:
12.1.3.3 Rule of Float Substitutability http://clhs.lisp.se/Body/12_acc.htm

It returns a type specifier that can be combined with intervals.
For example, when the contagion result is FIXNUM, it returns ’INTEGER instead.
Specifically, it returns one of ’integer, ’short-float, ... ’long-float, ’(complex integer),
’(complex short-float) ... ’(complex long-float) or nil (i.e. empty type).

The optional key argument :int-result can alter the behavior when the input is an integer.
This is useful for specifying the appropriate default behavior for rational functions
(e.g. mod: integer -> integer) and irrational functions (e.g. exp: integer -> float).

If the argument is FLOAT (without precision), it returns *numcl-default-float-format*.
If the argument is a type specifier for a concrete float subtype, it returns its primary type (e.g. ’single-float).
If the argument is a type specifier for an integer subtype, it returns the value of an optional key argument int-result, defaulted to ’integer. If the argument is a type specifier for a real subtype, it returns *numcl-default-float-format*.
If the argument is a complex type, it applies itself to the complex element type.

If the argument is a compound type (OR/AND), it applies itself to each type.
For OR, it returns the OR of each result.
For AND, all result should be eq to each other, otherwise NIL.

If the argument is a NIL type (empty type), NIL is returned.

For an unsupported type, it signals an error.

Package
Source
Function: float-to-integer-p (newtype oldtype)
Package
Source
Function: floor-inferer (x &optional y)
Package
Source
Function: funcall* (fn x &optional default)
Package
Source
Function: handle-sbcl-bug (fn x y)
Package
Source
Function: i-avar (i)

Variable for the input array

Package
Source
Function: i-avars (specs)
Package
Source
Function: i-evars (specs)
Package
Source
Function: i-idx (i)

Variable for the 1D index of input array

Package
Source
Function: i-idxs (specs)
Package
Source
Function: i-p (x)

dummy predicate for enabling the structure matching in trivia

Package
Source
Function: infer-logand (x y)
Package
Source
Function: infer-logandc1 (x y)
Package
Source
Function: infer-logandc2 (x y)
Package
Source
Function: infer-logeqv (x y)
Package
Source
Function: infer-logior (x y)
Package
Source
Function: infer-lognand (x y)
Package
Source
Function: infer-lognor (x y)
Package
Source
Function: infer-lognot (x)
Package
Source
Function: infer-logorc1 (x y)
Package
Source
Function: infer-logorc2 (x y)
Package
Source
Function: infer-rational-arithmetic-result (interval-op typespecs int-int-result)

Convert a set of type specifiers under REAL, e.g. RATIO, INTEGERS, FLOATS, to the least specific FLOAT type when any one of them are not fixnums.

Package
Source
Function: infer-type (name &rest args)
Package
Source
Function: infer-type-from-content (x)
Package
Source
Function: infer-type-from-contents (contents)
Package
Source
Function: inferer-boundp (symbol)

Automatically defined boolean function.

Package
Source
Function: inlinable-diag (a &optional result)

Return the diagonal element of a matrix as a vector

Package
Source
Function: inlinable-eye (n &key m k type)

Returns a matrix whose k-th diagnonal filled with 1.
N,M specifies the shape of the return array. K will adjust the sub-diagonal – positive K moves it upward.

Package
Source
Function: inlinable-inner (a b &optional result)

Inner product of two vectors.

Package
Source
Function: inlinable-kron (a b &optional result)

Compute the kronecker product of two vectors.

Package
Source
Function: inlinable-matmul (a b &optional result)

Matrix product of two arrays.

Package
Source
Function: inlinable-outer (a b &optional result)

Compute the outer product of two vectors.

Package
Source
Function: inlinable-transpose (matrix &optional result)

Reverses the axes of an array.

Package
Source
Function: inlinable-tri (n &key m k type)

Returns a triangle matrix whose lower diagnonal (including the diagonal) filled with 1.
N,M specifies the shape of the return array. K will adjust the sub-diagonal – positive K fills more 1s.

Package
Source
Function: inlinable-tril (matrix &optional k)

Returns the copy of matrix with elements above the k-th diagonal zeroed. Positive K fills less 0s.

Package
Source
Function: inlinable-triu (matrix &optional k)

Returns the copy of matrix with elements below the k-th diagonal zeroed. Positive K fills more 0s.

Package
Source
Function: inlinable-vander (v &key n increasing)

Returns a matrix where M[i,j] == V[i]^(N-j) when increasing is false (default), and M[i,j] == V[i]^j when increasing is true.

Package
Source
Function: inlinable-vdot (a b &optional result)

Dot product of two vectors. For complex values, the first value is conjugated.

Package
Source
Function: interpret-type (form)

Form is a cons tree in which: form : (inferer args*)
arg : type | form | singleton singleton : number

Package
Source
Function: intersection-to-float-type (&rest typespecs)
Package
Source
Function: interval-< (l1 h1 l2 h2)

Sort types accorting to the interval-designators. Provides a full ordering

Package
Source
Function: interval-add (l1 h1 l2 h2 &key)
Package
Source
Function: interval-ceiling (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-coerce (value type)
Package
Source
Function: interval-connected-p (l1 h1 l2 h2)
Package
Source
Function: interval-div (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-divlike (fn l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-fceiling (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-ffloor (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-floor (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-fround (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-ftruncate (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-intersection (l1 h1 l2 h2 &key)
Package
Source
Function: interval-max (l1 h1 l2 h2 &key)
Package
Source
Function: interval-min (l1 h1 l2 h2 &key)
Package
Source
Function: interval-mul (l1 h1 l2 h2 &key)
Package
Source
Function: interval-postprocess-high (x)
Package
Source
Function: interval-postprocess-low (x)
Package
Source
Function: interval-preprocess-high (x)
Package
Source
Function: interval-preprocess-low (x)
Package
Source
Function: interval-round (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-sub (l1 h1 l2 h2 &key)
Package
Source
Function: interval-truncate (l1 h1 l2 h2 &key divisor-type)
Package
Source
Function: interval-union (l1 h1 l2 h2 &key)
Package
Source
Function: isqrt-inferer (x)
Package
Source
Function: log-inferer (x)
Package
Source
Function: logr-inferer (x)

Inferer for the logarithm in positive inputs

Package
Source
Function: make-einsum-specs (&key iter-specs transforms i-specs i-options o-specs o-options)
Package
Source
Function: make-version-string ()
Package
Source
Function: map-specs (fn specs)
Package
Source
Function: matmul*-naive (&rest args)

Takes an arbitrary number of matrices and performs multiplication.

Package
Source
Function: matmul*-test ()
Package
Source
Function: matmul*-thrashdin (&rest args)

Takes an arbitrary number of matrices and performs multiplication, optimizing the order using the shape information and the associativity to minimize the size of the intermediate matrix.

Package
Source
Function: matrix-chain-order (dims n)
Package
Source
Function: max-to-float-type (&rest typespecs)
Package
Source
Function: memoized-einsum-function (normalized-subscripts)
Package
Source
Function: min-to-float-type (&rest typespecs)
Package
Source
Function: most-negative-value (type)
Package
Source
Function: most-positive-value (type)
Package
Source
Function: mul-to-float-type (&rest typespecs)
Package
Source
Function: nan-result-negative-lb (x)
Package
Source
Function: nan-result-negative-ub (x)
Package
Source
Function: nan-result-positive-lb (x)
Package
Source
Function: nan-result-positive-ub (x)
Package
Source
Function: normalize-index (index dimension)
Package
Source
Function: normalize-subscripts (subscripts shape)

Normalizes the input for %aref.

- corresponds to numpy’s elipses ‘...‘, and it should appear only once. t corresponds to the unspecified end in numpy’s ‘:‘ .

Package
Source
Function: o-avar (i)

Variable for the output array

Package
Source
Function: o-avars (specs)
Package
Source
Function: o-evars (specs)
Package
Source
Function: o-idx (i)

Variable for the 1D index of output array

Package
Source
Function: o-idxs (specs)
Package
Source
Function: o-p (x)

dummy predicate for enabling the structure matching in trivia

Package
Source
Function: one-value (type)
Package
Source

Store (precompute) the broadcast information in a matrix of size (2, N+1, M),
where N is the number of arrays (lengths of shapes) and
M is the maximum rank of the dimensions being broadcasted.

(0, 0, j) contains the dimension of the output arrays for axis j.
(0, i+1, j) contains the dimension of the i-th input array for axis j.
(1, 0, j) contains the step size of the output arrays for axis j.
(1, i+1, j) contains the step size of the i-th input array for axis j.

The step size for axis j is the product of the dimensions after j-th axes for that array.

This part of the code is run in the runtime, not in the compile time,
because it handles the runtime information of the size of the input arrays.

Package
Source
Function: postprocess (interval)
Package
Source
Function: range-width (array axis start end step)
Package
Source
Function: reduce-lambda (rank axes)
Package
Source
Function: rem-inferer (x y)
Package
Source
Function: result-shape (subscripts)
Package
Source
Function: round-inferer (x &optional y)
Package
Source
Function: safe-float-infinity-p (x)
Package
Source
Function: safe-float-nan-p (x)
Package
Source
Function: safe-string= (a b)
Package
Source
Function: sb (n num)

Truncate NUM as (signed-byte N) integer, preserving the sign

Package
Source
Function: set-type-inferer (name fname)
Package
Source
Function: shape-resolver (vars specs options &optional out-p)

Returns a list whose first value is a binding form for LET.
The rest of the elements are declaration and assertion forms for the body of let.

out-p: Produces the binding for output arrays.

Package
Source
Function: signed-zero-lb (x other)
Package
Source
Function: signed-zero-ub (x other)
Package
Source
Function: simplify-or-types (types)
Package
Source
Function: sin-inferer (x)
Package
Source
Function: sinh-inferer (x)
Package
Source
Function: sort-locality (indices subscripts)

In each iteration, greedily select the earliest index.
However, it penalize removing the index from the same set of subscripts that
the past indices are removed from.
This makes it easier to implement the block-matrix algorithms for improved cache locality.

Package
Source
Function: spec-depends-on (spec iter-specs)
Package
Source
Function: sqrt-inferer (x)
Package
Source
Function: strict-type-of (x)

stricter version of type-of, which does not simplify the type – e.g., (type-of 5) is (integer 5 5), not fixnum.

Package
Source
Function: sub (start stop step width full contiguous singleton)
Package
Source
Package
Source
Target Slot
Package
Source
Target Slot

full.

Function: sub-p (object)
Package
Source
Package
Source
Target Slot
Package
Source
Target Slot
Package
Source
Target Slot

step.

Package
Source
Target Slot

stop.

Function: sub-to-float-type (first &rest typespecs)
Package
Source
Package
Source
Target Slot
Function: symbol-inferer (symbol &optional default)

Automatically defined getter function. When DEFAULT is supplied, the value is set automatically.

Package
Source
Function: (setf symbol-inferer) (symbol)

Automatically defined setter function.

Package
Source
Function: tan-inferer (x)
Package
Source
Function: tanh-inferer (x)
Package
Source
Function: truncate-inferer (x &optional y)
Package
Source
Function: type-connected-p (t1 t2)
Package
Source
Function: type-interval-< (t1 t2)
Package
Source
Function: typexpand (type &optional env)
Package
Source
Function: ub (n num)

Truncate NUM as (unsigned-byte N) integer, ignoring the sign

Package
Source
Function: union-to-float-type (&rest typespecs)

Convert a set of type specifiers under REAL, e.g. RATIO, INTEGERS, FLOATS, to the least specific FLOAT type when any one of them are not fixnums.

When two interval designators are not connected, it returns OR types. If you want them to be merged as a single type, use bind-to-float-type.

Package
Source
Function: zero-value (type)
Package
Source

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.7 Generic functions

Generic Function: einsum-body (*compiler* einsum-specs)

* ‘*compiler*‘ : Special variable (supposed to be a keyword) used for dispatching the compilation scheme.

* ‘einsum-specs‘ : einsum-specs structure.

Package
Source
Methods
Method: einsum-body ((*compiler* (eql :common-lisp)) ev)
Source

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.8 Conditions

Condition: unbound-inferer
Package
Source
Direct superclasses

unbound-variable.

Next: , Previous: , Up: Internals   [Contents][Index]

#### 6.2.9 Structures

Structure: einsum-specs

A temporary structure holding the information for the einsum compiler.
* ‘iter-specs‘ : A list of integers that defines the nested loops.
For example, (0 1 2) for the ijk loop in gemm.

* ‘i-specs‘, ‘o-specs‘ : A list of lists of integers that specifies the indices for each input/output array. Each list should be a subset of iter-specs.
For example, ((0 1) (1 2) (0 2)) for the ijk loop in gemm.

* ‘transforms‘ : A list of forms. One form is for each output array. Each form is evaluated in each loop and the value is assigned to the array element.

Package
Source
Direct superclasses

structure-object.

Direct slots
Slot: iter-specs
Writers
Slot: transforms
Writers
Slot: i-specs
Writers
Slot: i-options
Writers
Slot: o-specs
Writers
Slot: o-options
Writers
Structure: sub

A structure that represents the range of iteration.
FULL When true, the entire elements in the axis is covered CONTIGUOUS When true, there are no gap in the range of iteration SINGLETON Differentiates the index (2 3) (== python [2:3]) and 2

Package
Source
Direct superclasses

structure-object.

Direct slots
Slot: start
Type

fixnum

Initform

0

Writers

Slot: stop
Type

fixnum

Initform

0

Writers

Slot: step
Package

common-lisp.

Type

fixnum

Initform

0

Writers

Slot: width
Type

fixnum

Initform

0

Writers

Slot: full
Package
Type

boolean

Writers

Slot: contiguous
Type

boolean

Writers

Slot: singleton
Type

boolean

Writers

Previous: , Up: Internals   [Contents][Index]

#### 6.2.10 Types

Type: base-array (&optional element-type length)

Type specifier for the base, 1D arrays for the NUMCL arrays.

Package
Source
Type: i ()
Package
Source
Type: index ()
Package
Source
Type: inferer-type ()
Package
Source
Type: o ()
Package
Source