The magicl Reference Manual

Table of Contents

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

The magicl Reference Manual

This is the magicl Reference Manual, version 0.9.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:59:36 2021 GMT+0.


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

1 Introduction

MAGICL

Matrix Algebra proGrams In Common Lisp by Rigetti Computing. (née FLAIL: Finally, Linear Algebra In Lisp!)

(Note: The high-level interface is experimental and subject to change.)

Requirements

MAGICL has two main systems:

The system MAGICL/CORE requires:

The system MAGICL, on the other hand, requires several foreign dependencies not shipped with MAGICL, like:

Detailed instructions on how to install libffi and BLAS/LAPACK can be found here.

Currently this library is SBCL- and CCL-only. The non-portable code is in with-array-pointers.lisp and magicl.lisp.

Installation

First ensure you have the necessary requirements installed, as described in the previous section.

To install MAGICL, clone this repository into your Quicklisp's local-projects folder. You can quickly check where this is by running sbcl and evaluating ql:*local-project-directories*. Once installed, confirm that MAGICL is working properly by running the tests, as described in the next section.

Lisp-Only vs Accelerated MAGICL

Extensions

MAGICL/CORE only uses pure ANSI Common Lisp code. If you wish to accelerate it or extend the functionality, you may load MAGICL extensions. These extensions typically install new backends to MAGICL functions. The available extensions are:

For backwards compatibility, MAGICL loads every extension under the kitchen sink. This may change in future versions of MAGICL! If you depend on an extension, depend on it explicitly!

If you use extensions, you'll need the requisite C/Fortran libraries. Expokit will automatically build for you, as its source is included in the distribution of MAGICL.

Backends

Accelerated functionality is installed with a notion called "backends". A backend is a name of a group of functionality, typically denoted by a symbol or keyword. The :lisp backend is the defualt one, and several backends can be active all at once. Each extension above adds a new backend. The current backends are:

In most cases, one does not need to concern themselves with backends; MAGICL functionality should "just work" and dispatch to the appropriate backend. However, the programmer always has control, even dynamically in the program, of which backends should be used at a given time with the magicl.backends:with-backends macro. For instance,

(magicl.backends:with-backends (:blas :lisp)
  ;; ... code ...
  )

says that the code should be executed, always preferring :blas-accelerated functions, and using :lisp-implemented functions as a fall-back.

(magicl.backends:with-backends (:lisp)
  ;; ... code ...
  )

says to only use :lisp-implemented functions, even if other backends are loaded.

The active backends can be found with the function magicl.backends:active-backends, which lists the backends to use in priority order.

One can be even finer-grained than with-backends. Given a function f which has many backend implementations, one can get a specific implementation by using the function:

(magicl.backends:backend-implementation 'f :backend-name)

For instance

(magicl.backends:backend-implementation 'magicl:csd :lapack)

will give the implementation of the cosine-sine decomposition function in LAPACK. This can be called in exactly the same way magicl:csd can be called.

In backend-implementation, if both the function name and the backend name are (quoted) constants, this will be looked up at compile-time, which is useful for writing efficient code that does not dispatch. But note that by doing this, with-backends will not be respected.

Testing MAGICL

You can run the MAGICL tests from your Lisp REPL with:

(asdf:test-system :magicl)

You currently need all of the extensions working for the tests to run.

High-level Interface

See the high-level doc for an extensive discussion and comparison of MAGICL functions with those of MATLAB and NumPy.

Developer's Guide: How to Add New Functions

See the developer how-to to understand how to add new functionality to MAGICL.

Fortran Bindings

See the Fortran Functions on how to re-generate the Fortran bindings from the original BLAS, LAPACK, and Expokit reference code.

See the same document for how to query for available Fortran functions in the currently loaded dynamic libraries.

History and Credits

MAGICL development started at Rigetti Computing by Robert Smith and Joe Lin in 2017.

CL-BLAPACK is a library developed by Ryan Rifkin and Evan Monroig. Rigetti Computing created a fork of this library and renamed it MAGICL, and made significant changes that departed from the original design, including:

The most important common design decision between CL-BLAPACK and MAGICL is allowing direct access to the Fortran library functions by way of automatically generated Lisp bindings from the reference sources.


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

2 Systems

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


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

2.1 magicl

Maintainer

Rigetti Computing

Author

Rigetti Computing

License

BSD 3-Clause (See LICENSE.txt)

Description

Matrix Algebra proGrams In Common Lisp

Version

0.9.1

Dependencies
Source

magicl.asd (file)


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

2.2 magicl/ext-expokit

Maintainer

Rigetti Computing

Author

Rigetti Computing

License

BSD 3-Clause (See LICENSE.txt)

Description

Expokit for MAGICL.

Dependencies
Source

magicl.asd (file)

Components

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

2.3 magicl/ext-lapack

Maintainer

Rigetti Computing

Author

Rigetti Computing

License

BSD 3-Clause (See LICENSE.txt)

Description

Native LAPACK routines in MAGICL.

Dependencies
Source

magicl.asd (file)

Components

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

2.4 magicl/ext-blas

Maintainer

Rigetti Computing

Author

Rigetti Computing

License

BSD 3-Clause (See LICENSE.txt)

Description

Native BLAS routines in MAGICL.

Dependencies
Source

magicl.asd (file)

Components

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

2.5 magicl/core

Maintainer

Rigetti Computing

Author

Rigetti Computing

License

BSD 3-Clause (See LICENSE.txt)

Description

Matrix Algebra proGrams In Common Lisp (pure Lisp core)

Version

0.9.1

Dependencies
Source

magicl.asd (file)

Components

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

2.6 magicl/ext

Maintainer

Rigetti Computing

Author

Rigetti Computing

License

BSD 3-Clause (See LICENSE.txt)

Description

Common code for extending MAGICL with foreign libraries.

Dependencies
Source

magicl.asd (file)

Components

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

3 Modules

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


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

3.1 magicl/ext-expokit/expokit

Parent

magicl/ext-expokit (system)

Location

expokit/

Component

expokit.f (file)


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

3.2 magicl/ext-expokit/src/extensions/expokit

Dependency

expokit (module)

Parent

magicl/ext-expokit (system)

Location

src/extensions/expokit/

Components

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

3.3 magicl/ext-lapack/bindings

Dependency

extensions/lapack/load-libs.lisp (file)

Parent

magicl/ext-lapack (system)

Location

src/bindings/

Components

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

3.4 magicl/ext-lapack/extensions/lapack

Dependency

bindings (module)

Parent

magicl/ext-lapack (system)

Location

src/extensions/lapack/

Components

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

3.5 magicl/ext-blas/bindings

Dependency

extensions/blas/load-libs.lisp (file)

Parent

magicl/ext-blas (system)

Location

src/bindings/

Component

blas-cffi.lisp (file)


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

3.6 magicl/core/high-level

Dependency

benchmark-utilities.lisp (file)

Parent

magicl/core (system)

Location

src/high-level/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 magicl.asd

Location

magicl.asd

Systems

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

4.1.2 magicl/ext-expokit/src/extensions/expokit/package.lisp

Parent

src/extensions/expokit (module)

Location

src/extensions/expokit/package.lisp

Packages

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

4.1.3 magicl/ext-expokit/src/extensions/expokit/load-libs.lisp

Parent

src/extensions/expokit (module)

Location

src/extensions/expokit/load-libs.lisp

Internal Definitions

*expokit-libs-loaded* (special variable)


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

4.1.4 magicl/ext-expokit/src/bindings/expokit-cffi.lisp

Dependency

src/extensions/expokit (module)

Parent

magicl/ext-expokit (system)

Location

src/bindings/expokit-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.5 magicl/ext-expokit/src/extensions/expokit/expm.lisp

Dependency

src/bindings/expokit-cffi.lisp (file)

Parent

magicl/ext-expokit (system)

Location

src/extensions/expokit/expm.lisp

Internal Definitions

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

4.1.6 magicl/ext-lapack/extensions/lapack/package.lisp

Parent

magicl/ext-lapack (system)

Location

src/extensions/lapack/package.lisp

Packages

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

4.1.7 magicl/ext-lapack/extensions/lapack/load-libs.lisp

Dependency

extensions/lapack/package.lisp (file)

Parent

magicl/ext-lapack (system)

Location

src/extensions/lapack/load-libs.lisp

Internal Definitions

*blapack-libs-loaded* (special variable)


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

4.1.8 magicl/ext-lapack/bindings/lapack00-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack00-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.9 magicl/ext-lapack/bindings/lapack01-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack01-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.10 magicl/ext-lapack/bindings/lapack02-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack02-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.11 magicl/ext-lapack/bindings/lapack03-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack03-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.12 magicl/ext-lapack/bindings/lapack04-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack04-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.13 magicl/ext-lapack/bindings/lapack05-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack05-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.14 magicl/ext-lapack/bindings/lapack06-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack06-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.15 magicl/ext-lapack/bindings/lapack07-cffi.lisp

Parent

bindings (module)

Location

src/bindings/lapack07-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.16 magicl/ext-lapack/extensions/lapack/lapack-generics.lisp

Parent

extensions/lapack (module)

Location

src/extensions/lapack/lapack-generics.lisp

Exported Definitions
Internal Definitions

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

4.1.17 magicl/ext-lapack/extensions/lapack/lapack-templates.lisp

Parent

extensions/lapack (module)

Location

src/extensions/lapack/lapack-templates.lisp

Internal Definitions

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

4.1.18 magicl/ext-lapack/extensions/lapack/lapack-bindings.lisp

Parent

extensions/lapack (module)

Location

src/extensions/lapack/lapack-bindings.lisp

Exported Definitions
Internal Definitions

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

4.1.19 magicl/ext-lapack/extensions/lapack/lapack-csd.lisp

Parent

extensions/lapack (module)

Location

src/extensions/lapack/lapack-csd.lisp

Exported Definitions

lapack-csd (method)

Internal Definitions

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

4.1.20 magicl/ext-blas/extensions/blas/package.lisp

Parent

magicl/ext-blas (system)

Location

src/extensions/blas/package.lisp

Packages

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

4.1.21 magicl/ext-blas/extensions/blas/load-libs.lisp

Dependency

extensions/blas/package.lisp (file)

Parent

magicl/ext-blas (system)

Location

src/extensions/blas/load-libs.lisp

Internal Definitions

*blas-loaded* (special variable)


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

4.1.22 magicl/ext-blas/bindings/blas-cffi.lisp

Parent

bindings (module)

Location

src/bindings/blas-cffi.lisp

Exported Definitions
Internal Definitions

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

4.1.23 magicl/ext-blas/extensions/blas/arithmetic.lisp

Dependency

bindings (module)

Parent

magicl/ext-blas (system)

Location

src/extensions/blas/arithmetic.lisp

Internal Definitions

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

4.1.24 magicl/core/packages.lisp

Parent

magicl/core (system)

Location

src/packages.lisp

Packages

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

4.1.25 magicl/core/backend-function.lisp

Dependency

packages.lisp (file)

Parent

magicl/core (system)

Location

src/backend-function.lisp

Exported Definitions
Internal Definitions

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

4.1.26 magicl/core/benchmark-utilities.lisp

Dependency

backend-function.lisp (file)

Parent

magicl/core (system)

Location

src/benchmark-utilities.lisp

Exported Definitions

time-backends (function)


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

4.1.27 magicl/core/high-level/util.lisp

Parent

high-level (module)

Location

src/high-level/util.lisp

Exported Definitions

define-extensible-function (macro)

Internal Definitions

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

4.1.28 magicl/core/high-level/shape.lisp

Dependency

util.lisp (file)

Parent

high-level (module)

Location

src/high-level/shape.lisp

Exported Definitions

shape (type)

Internal Definitions

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

4.1.29 magicl/core/high-level/abstract-tensor.lisp

Dependency

shape.lisp (file)

Parent

high-level (module)

Location

src/high-level/abstract-tensor.lisp

Exported Definitions
Internal Definitions

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

4.1.30 magicl/core/high-level/specialize-tensor.lisp

Dependency

abstract-tensor.lisp (file)

Parent

high-level (module)

Location

src/high-level/specialize-tensor.lisp

Exported Definitions
Internal Definitions

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

4.1.31 magicl/core/high-level/tensor.lisp

Dependency

specialize-tensor.lisp (file)

Parent

high-level (module)

Location

src/high-level/tensor.lisp

Exported Definitions
Internal Definitions

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

4.1.32 magicl/core/high-level/matrix.lisp

Dependency

tensor.lisp (file)

Parent

high-level (module)

Location

src/high-level/matrix.lisp

Exported Definitions
Internal Definitions

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

4.1.33 magicl/core/high-level/vector.lisp

Dependency

matrix.lisp (file)

Parent

high-level (module)

Location

src/high-level/vector.lisp

Exported Definitions
Internal Definitions

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

4.1.34 magicl/core/high-level/types/single-float.lisp

Dependency

vector.lisp (file)

Parent

high-level (module)

Location

src/high-level/types/single-float.lisp

Exported Definitions
Internal Definitions

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

4.1.35 magicl/core/high-level/types/double-float.lisp

Dependency

types/single-float.lisp (file)

Parent

high-level (module)

Location

src/high-level/types/double-float.lisp

Exported Definitions
Internal Definitions

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

4.1.36 magicl/core/high-level/types/complex-single-float.lisp

Dependency

types/double-float.lisp (file)

Parent

high-level (module)

Location

src/high-level/types/complex-single-float.lisp

Exported Definitions
Internal Definitions

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

4.1.37 magicl/core/high-level/types/complex-double-float.lisp

Dependency

types/complex-single-float.lisp (file)

Parent

high-level (module)

Location

src/high-level/types/complex-double-float.lisp

Exported Definitions
Internal Definitions

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

4.1.38 magicl/core/high-level/types/int32.lisp

Dependency

types/complex-double-float.lisp (file)

Parent

high-level (module)

Location

src/high-level/types/int32.lisp

Exported Definitions
Internal Definitions

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

4.1.39 magicl/core/high-level/constructors.lisp

Dependency

types/int32.lisp (file)

Parent

high-level (module)

Location

src/high-level/constructors.lisp

Exported Definitions
Internal Definitions

*default-tensor-type* (special variable)


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

4.1.40 magicl/core/high-level/specialize-constructor.lisp

Dependency

constructors.lisp (file)

Parent

high-level (module)

Location

src/high-level/specialize-constructor.lisp

Internal Definitions

infer-tensor-type (function)


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

4.1.41 magicl/core/high-level/polynomial-solver.lisp

Dependency

specialize-constructor.lisp (file)

Parent

high-level (module)

Location

src/high-level/polynomial-solver.lisp

Exported Definitions
Internal Definitions

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

4.1.42 magicl/core/magicl.lisp

Dependency

high-level (module)

Parent

magicl/core (system)

Location

src/magicl.lisp

Exported Definitions

with-blapack (macro)


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

4.1.43 magicl/ext/package.lisp

Parent

magicl/ext (system)

Location

src/extensions/common/package.lisp

Packages

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

4.1.44 magicl/ext/library-tracking.lisp

Dependency

package.lisp (file)

Parent

magicl/ext (system)

Location

src/extensions/common/library-tracking.lisp

Exported Definitions

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

4.1.45 magicl/ext/with-array-pointers.lisp

Dependency

library-tracking.lisp (file)

Parent

magicl/ext (system)

Location

src/extensions/common/with-array-pointers.lisp

Exported Definitions

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

4.1.46 magicl/ext/cffi-types.lisp

Dependency

with-array-pointers.lisp (file)

Parent

magicl/ext (system)

Location

src/extensions/common/cffi-types.lisp

Internal Definitions

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

4.2 Other


Previous: , Up: Other files   [Contents][Index]

4.2.1 magicl/ext-expokit/expokit/expokit.f

Parent

expokit (module)

Location

expokit/expokit.f


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

5 Packages

Packages are listed by definition order.


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

5.1 magicl.expokit-cffi

Source

package.lisp (file)

Exported Definitions
Internal Definitions

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

5.2 magicl-expokit

Source

package.lisp (file)

Use List
Internal Definitions

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

5.3 magicl-lapack

Source

extensions/lapack/package.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

5.4 magicl.lapack-cffi

Source

extensions/lapack/package.lisp (file)

Exported Definitions