lsci

Scientific Computing on the Erlang VM - An LFE Wrapper Library for SciPy, NumPy, and matplotlib

Table of Contents

• Introduction
• Requirements
• Installation
• Usage
  • From LFE
  • From Erlang
  • Wrapped Library Docs
• Development

Introduction ↟

This project has the lofty goal of making numerical processing an efficient and easy thing to do in LFE/Erlang. The engine behind this work is ErlPort.

Here is a list of the Python packages lsci aims to wrap, annotated with the current development status:

• math - complete
• cmath - complete
• statistics - complete
• fractions - complete
• decimal - in progress
• NumPy - in progress
• SciPy - in progress
• Pandas - not started
• matplotlib - not started
• SymPy - not started

Quick sample:

> (set array (lsci-np:array '((1 2 3) (4 5 6) (7 8 9))))
#($erlport.opaque python
  #B(128 2 99 110 117 109 112 121 46 99 111 114 101 46 109 117 108 ...))
> (lsci-np:size array)
9
> (lsci-np:shape array)
#(3 3)

And it's pronounced "Elsie".

Requirements ↟

To use lsci, you need the following:

• lfetool
• Python 3

Installation ↟

For now, just run it from a git clone:

$ git clone [email protected]:lfex/lsci.git
$ cd lsci
$ make

Usage ↟

Activate your Python virtualenv and then start up the LFE REPL:

$ . ./python/.venv/bin/activate
$ make repl-no-deps

Note that the repl and repl-no-deps targets automatically start up the lsci (and thus ErlPort) Erlang Python server. If you run the REPL without these make targets, you'll need to manually start things:

$ lfetool repl lfe -s lsci

Below we show some basic usage of lsci from both LFE and Erlang. In a separate section a list of docs are linked showing detailed usage of wrapped libraries.

From LFE ↟

You should be in your REPL at the terminal:

Erlang/OTP 17 [erts-6.3] [source] [64-bit] [smp:4:4] [async-threads:10] ...

LFE Shell V6.3 (abort with ^G)
>

First things first: let's make sure that you have the appropriate versions of things -- in particular, let's confirm that you're running Python 3:

> (lsci-util:get-versions)
(#(erlang "17")
 #(emulator "6.2")
 #(driver-version "3.1")
 #(lfe "0.9.0")
 #(erlport "0.9.8")
 #(py "0.0.2")
 #(lsci "0.0.1")
 #(python
   ("3.4.2 (v3.4.2:ab2c023a9432, Oct  5 2014, 20:42:22)"
    "[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)]"))
 #(numpy "1.9.1")
 #(scipy "0.14.0"))

lsci comes with py, so you can make calls with that library:

> (py:func 'os 'getcwd)
"/Users/yourname/lab/erlang/lsci"

And then of course, math, NumPy, etc.:

> (lsci-math:pow 2 32)
4294967296.0
> (set array (lsci-np:array '((1 2 3) (4 5 6) (7 8 9))))
#($erlport.opaque python
  #B(128 2 99 110 117 109 112 121 46 99 111 114 101 46 109 117 108 ...))
> (lsci-np:size array)
9
> (lsci-np:shape array)
#(3 3)

From Erlang ↟

We can do the same thing from Erlang:

$ make shell-no-deps

1> 'lsci-util':'get-versions'().
[{erlang,"17"},
 {emulator,"6.2"},
 {'driver-version',"3.1"},
 {lfe,"0.9.0"},
 {erlport,"0.9.8"},
 {py,"0.0.2"},
 {lsci,"0.0.1"},
 {python,["3.4.2 (v3.4.2:ab2c023a9432, Oct  5 2014, 20:42:22)",
          "[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)]"]},
 {numpy,"1.9.1"},
 {scipy,"0.14.0"}]
2> py:func(os, getcwd).
"/Users/yourname/lab/erlang/lsci"
3> 'lsci-math':pow(2, 32).
4294967296.0
4> Array = 'lsci-np':array([[1,2,3], [4,5,6],[7,8,9]]).
{'$erlport.opaque',python,
                   <<128,2,99,110,117,109,112,121,46,99,111,114,101,46,109,
                     117,108,116,105,97,114,114,97,121,10,95,...>>}
5> 'lsci-np':size(Array).
9
6> 'lsci-np':shape(Array).
{3,3}

Wrapped Library Docs ↟

More detailed usage information is provided in separate docs, per-wrapped library:

• lsci-math & lsci-cmath - The math and cmath Python Standard library modules in LFE
• lsci-stats - The statistics Python 3 Standard library module in LFE
• lsci-frac - The fractions Python 3 Standard library module in LFE
• lsci-np - NumPy in LFE
• lsci-sp - SciPy in LFE
• lsci-pd - Pandas in LFE (TBD)
• lsci-mpl - matplotlib in LFE (TBD)
• lsci-sym - SymPy in LFE (TBD)

Development ↟

Features waiting to be implemented are created as issues; check them out to see how you can contribute.

Read up on py to get a feeling for how lsci works.

To understand how the wrapping is done in lsci, check out the kla project and some libraries that use it.

For insight on how lsci, LFE, and Erlang can interface with Python, see the ErlPort docs.