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.6.2, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Fri May 24 09:21:45 2019 GMT+0.


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

1 Introduction

MAGICL

Build Status

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

Load it with (ql:quickload :magicl).

Test it with (asdf:test-system :magicl).

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

Requirements

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.

Testing MAGICL

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

(ql:quickload :magicl-tests)
(asdf:test-system :magicl)

This repository is also set up with Sempahore CI, and uses Docker for building MAGICL and running its tests. You can emulate Semaphore's behavior by using the following commands from the top-level directory:

make -C docker
make -C docker test

Note, doing this requires that you have docker installed on your machine.

Showing Available Functions

Some distributions of a library don't actually provide all of the functions of the reference BLAS and LAPACK. One can look at a summary of available and unavailable functions with the function magicl:print-availability-report. By default, it will show all functions and their availability. There are three arguments to fine-tune this behavior:

  1. Key :show-available <boolean> (default t): show available functions
  2. Key :show-unavailable <boolean> (default t): show unavailable functions
  3. Key :search <string>: only show functions which have <string> as a substring. This argument takes into account the previous two arguments.

For example, we can look for all available functions which might relate to svd by doing the following:

CL-USER> (magicl:print-availability-report :search "svd" :show-unavailable nil)
        Fortran Function        Lisp Function
------------------------------------------------------------------------

Library LIBBLAS: /usr/local/opt/lapack/lib/libblas.dylib

Library LIBLAPACK: /usr/local/opt/lapack/lib/liblapack.dylib
    [x] CGESVD                  MAGICL.LAPACK-CFFI:%CGESVD
    [x] CGESVDX                 MAGICL.LAPACK-CFFI:%CGESVDX
    [x] CGGSVD3                 MAGICL.LAPACK-CFFI:%CGGSVD3
    [x] DBDSVDX                 MAGICL.LAPACK-CFFI:%DBDSVDX
    [x] DGESVD                  MAGICL.LAPACK-CFFI:%DGESVD
    [x] DGESVDX                 MAGICL.LAPACK-CFFI:%DGESVDX
    [x] DGGSVD3                 MAGICL.LAPACK-CFFI:%DGGSVD3
    [x] SBDSVDX                 MAGICL.LAPACK-CFFI:%SBDSVDX
    [x] SGESVD                  MAGICL.LAPACK-CFFI:%SGESVD
    [x] SGESVDX                 MAGICL.LAPACK-CFFI:%SGESVDX
    [x] SGGSVD3                 MAGICL.LAPACK-CFFI:%SGGSVD3
    [x] ZGESVD                  MAGICL.LAPACK-CFFI:%ZGESVD
    [x] ZGESVDX                 MAGICL.LAPACK-CFFI:%ZGESVDX
    [x] ZGGSVD3                 MAGICL.LAPACK-CFFI:%ZGGSVD3

Generating BLAS and LAPACK Bindings

This library takes the approach of automatically generating the bindings to BLAS, LAPACK, and Expokit without relying on any special tools.

In order to generate the bindings, you will need to download the Fortran 90 source tarballs for BLAS/LAPACK and Expokit. Once downloaded, extract the tarballs into a directory and re-generate the bindings with the following commands:

(ql:quickload :magicl-gen)
(in-package :magicl.generate-interface)
(generate-blapack-files #P"/path/to/lapack-3.7.1/")
(generate-expokit-files #P"/path/to/expokit/")

Currently this will write to the source distribution directory of MAGICL, namely the files blas-cffi.lisp, lapack-cffi.lisp, and expokit-cffi.lisp.

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.


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

Dependencies
Source

magicl.asd (file)

Components

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

3 Files

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


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

3.1 Lisp


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

3.1.1 magicl.asd

Location

magicl.asd

Systems

magicl (system)


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

3.1.2 magicl/packages.lisp

Parent

magicl (system)

Location

packages.lisp

Packages

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

3.1.3 magicl/load-libs.lisp

Dependency

packages.lisp (file)

Parent

magicl (system)

Location

load-libs.lisp

Exported Definitions
Internal Definitions

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

3.1.4 magicl/with-array-pointers.lisp

Dependency

load-libs.lisp (file)

Parent

magicl (system)

Location

with-array-pointers.lisp

Exported Definitions

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

3.1.5 magicl/cffi-types.lisp

Dependency

with-array-pointers.lisp (file)

Parent

magicl (system)

Location

cffi-types.lisp

Internal Definitions

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

3.1.6 magicl/blas-cffi.lisp

Dependency

cffi-types.lisp (file)

Parent

magicl (system)

Location

blas-cffi.lisp

Exported Definitions
Internal Definitions

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

3.1.7 magicl/lapack-cffi.lisp

Dependency

blas-cffi.lisp (file)

Parent

magicl (system)

Location

lapack-cffi.lisp

Exported Definitions
Internal Definitions

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

3.1.8 magicl/high-level.lisp

Dependency

lapack-cffi.lisp (file)

Parent

magicl (system)

Location

high-level.lisp

Exported Definitions
Internal Definitions

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

3.1.9 magicl/random.lisp

Dependency

high-level.lisp (file)

Parent

magicl (system)

Location

random.lisp

Exported Definitions

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

3.1.10 magicl/magicl.lisp

Dependency

random.lisp (file)

Parent

magicl (system)

Location

magicl.lisp

Exported Definitions

with-blapack (macro)


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

4 Packages

Packages are listed by definition order.


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

4.1 magicl.blas-cffi

Source

packages.lisp (file)

Exported Definitions
Internal Definitions

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

4.2 magicl.expokit-cffi

Source

packages.lisp (file)


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

4.3 magicl.cffi-types

Source

packages.lisp (file)

Use List
Exported Definitions
Internal Definitions

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

4.4 magicl.lapack-cffi

Source

packages.lisp (file)

Exported Definitions
Internal Definitions