Language.J

Marshal a limited subset of J arrays into Repa arrays.

Tutorial

Suppose we wish to perform linear regression. In J we could do:

xs := 1 2 3
ys := 2 4 6

reg_result =: ys %. xs ^/ i.2

To do this with Haskell data:

do
   jenv <- jinit libLinux

   let hsArr0 = R.fromListUnboxed (R.ix1 3) [1.0,2.0,3.0]
       hsArr1 = R.fromListUnboxed (R.ix1 3) [2.0,4.0,6.0]
       jArr0 = JDoubleArr $ R.copyS $ R.map (realToFrac :: Double -> CDouble) hsArr0
       jArr1 = JDoubleArr $ R.copyS $ R.map (realToFrac :: Double -> CDouble) hsArr1

   setJData jenv "xs" jArr0
   setJData jenv "ys" jArr1

   bsDispatch jenv "reg_result =: ys %. xs ^/ i.2"

   JDoubleArr res <- getJData jenv "reg_result"
   R.toList res

There are three steps to do the calculation, plus one to get a J environment.

1. Use jinit with the appropriate file path for your platform
2. Marshal Haskell values and send them to the J environment. To do so, we use setJData, which takes a JData containing a repa array or a string.
3. Perform calculations within the J environment. Here, we use bsDispatch to compute some results and assign them within J
4. Marshal J values back to Haskell. We use getJData.

Since marshaling data between J and Haskell is expensive, it's best to do as much computation as possible in J.

Loading Profile

If you would like to use user libraries, you need to use jLoad on the JEnv. As an example:

 do
     jenv <- jinit libLinux
     jLoad jenv (linuxProfile "9.02")
     bsDispatch jenv "load'tables/csv'"
 

This will load the CSV addon, assuming it is installed.

FFI

If you want to marshal data yourself, say to use a Vector, look at JEnv.

Environment

data JEnv

Constructors

JEnv

Fields

• context :: Ptr J
• evaluator :: JDoType
• reader :: JGetMType
• out :: JGetRType
• setter :: JSetAType

jinit

Arguments

:: RawFilePath

Path to J library

-> IO JEnv

Get a J environment

Passing the resultant JEnv between threads can cause unexpected bugs.

jLoad :: JEnv -> Profile -> IO ()

Load user profile.

since 0.1.2.0

data Profile

Since: 0.1.2.0

Constructors

Profile

Fields

• profPath :: ByteString

  profile.ijs

• binPath :: ByteString
• dllName :: ByteString

linuxProfile

Arguments

:: ByteString

J version, e.g. "9.02"

-> Profile

Since: 0.1.2.0

macProfile :: JVersion -> Profile

Since: 0.1.2.0

windowsProfile :: JVersion -> Profile

Since: 0.1.2.0

libLinux :: RawFilePath

Expected RawFilePath to the library on a Linux machine.

libMac :: JVersion -> RawFilePath

Expected RawFilePath to the library on Mac.

profLinux :: ByteString -> ByteString

bsDispatch :: JEnv -> ByteString -> IO ()

Send some J code to the environment.

bsOut :: JEnv -> IO ByteString

Read last output

For debugging

type JVersion = [Int]

Repa

data JData sh

J data backed by repa array

Constructors

JIntArr !(Array F sh CLLong)

JDoubleArr !(Array F sh CDouble)

JComplexArr !(Array F sh (Complex CDouble))

JBoolArr !(Array F sh CChar)

JString !ByteString

getJData

Arguments

:: Shape sh

=> JEnv

-> ByteString

Name of the value in question

-> IO (JData sh)

\( O(n) \) in the array size

Throws JErr for unspported conversion types.

setJData

Arguments

:: Shape sh

=> JEnv

-> ByteString

Name

-> JData sh

-> IO CInt

\( O(n) \) in the array size

Exceptions

data JErr

Constructors

TypeError

UnsupportedType

Instances

Show JErr

Defined in Language.J

Methods

showsPrec :: Int -> JErr -> ShowS

show :: JErr -> String

showList :: [JErr] -> ShowS

Exception JErr

Defined in Language.J

Methods

toException :: JErr -> SomeException

fromException :: SomeException -> Maybe JErr

displayException :: JErr -> String

Vector helpers

tryIntVect :: JData DIM1 -> Vector Int

Copy into a Vector Int, if possible.

Throws a JErr on type error.

\( O(n) \)

copyIntVect :: Vector Int -> JData DIM1

\( O(n) \)

FFI

data J

Abstract context

type JDoType = Ptr J -> CString -> IO CInt

type JGetMType = Ptr J -> CString -> Ptr CLLong -> Ptr CLLong -> Ptr (Ptr CLLong) -> Ptr (Ptr CChar) -> IO CInt

type JGetRType = Ptr J -> IO CString

type JSetAType = Ptr J -> CLLong -> CString -> CLLong -> Ptr () -> IO CInt