doc.txt

MrMathematica * Zhu ChongKai

  _MrMathematica_  *  _Zhu ChongKai_
======================================


MrMathematica allows you to call _Mathematica_ from 
Scheme.

> MathKernel : [byte-string*] -> MathLink

Load the Mathematica kernel and return a _MathLink_. The 
argument(s) is command to open the MathLink connection. If 
not presented, MrMathematica will use #"-linkname" #"math 
-MathLink" as default, which in general will always open 
the Mathematica kernel. See the Mathmatica Book 2.13.14 
"Running Mathematica from Within an External Program" for 
more about this. The return value, a MathLink, is a value 
indicates the Mathematica kernel. It can be save to a 
variable and later used to distinguish different 
Mathematica kernel.

> MathEval : S-exp [MathLink] -> S-exp

Use Mathematica Kernel to evaluate. You should write the 
S-exp in Scheme style and they will be translated to 
Mathematica style automatically. Only numbers, booleans, 
symbols, strings, voids or none empty lists are allowed in 
the input. Otherwise exn:application:contract will be 
raised.

The optional argment, MathLink, specifies using which 
Mathematica kernel to do the computation. If no MathLink is 
given, MrMathematica will automatically choose the latest 
open (live) MathLink, or if no open MathLink is available, 
create one by calling MathKernel with no arguments. So, if 
you only want to use one Mathematica kernel at a time, just 
call MathEval with only one argument, and even need not to 
know the existence of MathKernel.

> MathExit : [MathLink] -> void

Close the Mathematica Kernel. If no MathLink is given, 
MrMathematica automatically close the latest open (live) 
MathLink. Please avoid using closed MathLink, otherwise 
exn:mathematica will be raised.

> MathLink? : exp -> boolean

Check whether the argument is a MathLink.

> living-MathLink? : exp -> boolean

Check whether the argument is a living MathLink.



Translation between Scheme and Mathematica: 

S-exp such as '(f x y) will be translated to f[x,y] and 
send to Mathematica Kernel. The return expression of 
Mathematica will be translated back into Scheme. Besides 
that, MrMathematica also use the following dictionary 
to translate function names:

'((* . Times)
  (- . Minus)
  (+ . Plus)
  (/ . Divide)
  (< . Less)
  (<= . LessEqual)
  (= . Equal)
  (> . Greater)
  (>= . GreaterEqual)
  (abs . Abs)
  (acos . ArcCos)
  (and . And)
  (angle . Arg)
  (asin . ArcSin)
  (atan . ArcTan)
  (begin . CompoundExpression)
  (ceiling . Ceiling)
  (cos . Cos)
  (denominator . Denominator)
  (exp . Exp)
  (expt . Power)
  (floor . Floor)
  (gcd . GCD)
  (if . If)
  (imag-part . Im)
  (lcm . LCM)
  (list . List)
  (log . Log)
  (magnitude . Abs)
  (max . Max)
  (min . Min)
  (modulo . Mod)
  (negative? . Negative)
  (not . Not)
  (number? . NumberQ)
  (numerator . Numerator)
  (or . Or)
  (positive? . Positive)
  (quotient . Quotient)
  (rationalize . Rationalize)
  (round . Round)
  (sin . Sin)
  (sqrt . Sqrt)
  (string-length . StringLength)
  (tan . Tan)
  (truncate . IntegerPart))

The translation table is defined in "translation.ss". If 
you just want no translation, change this file so that the 
two funcions the module provides are both the identity 
function.

There are some other functions that are similar in 
Mathematica and Scheme. According to the need, you can also 
add translation rules into the table. Here I list some such 
function pairs: 

append  Join
apply  Apply
build-list  Array
car  First
cdr  Rest
collect-garbage  Share
compose  Composition
cond  Which
cons  Prepend
copy-file  CopyFile/CopyDirectory
current-directory  Directory/SetDirectory
current-memory-use  MemoryInUse
current-process-milliseconds  TimeUsed
current-seconds  AbsoluteTime
define  Set
delay  Hold/Unevaluated
delete-directory  DeleteDirectory
delete-file  DeleteFile
directory-list  FileNames
display  Print
even?  EvenQ
exit  Exit/Quit
file-or-directory-modify-seconds  FileDate/SetFileDate
file-size  FileByteCount
filter  Select
fluid-let  Block
foldl  Fold
for-each  Scan
force  ReleaseHold/Evaluate
getenv  Environment
identity  Identity
integer?  IntegerQ
lambda  Function
length  Length
let  Module
list-ref  Part
list-tail  Drop
map  Map
make-directory  CreateDirectory
member/memq/memv  MemberQ
nand  Nand
nor  Nor
odd?  OddQ
pair?  AtomQ
read  Input
rename-file-or-directory  RenameFile/RenameDirectory
reverse  Reverse
shell-execute  Run/RunThrough
sleep  Pause
string->symbol  Symbol
string-append  StringJoin
symbol->string  SymbolName
system-type  $System
time  Timing
version  $Version
zero?  ZeroQ

Notice that they are not identical so some rules should be 
conditional. Learn the default rule of '- for details.