MrMathematica * ChongKai Zhu

  _MrMathematica_  *  _ChongKai Zhu_
======================================

MrMathematica allows you to call _Mathematica_ from PLT Scheme, or 
call PLT Scheme from Mathematica.

_mathematica.ss_
----------------

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

Open a _MathLink_ connectiona. The arguments are passed to 
MLOpenArgv. Check Mathematica/MathLink document for details about 
the arguments. If not presented, MrMathematica will use #"-linkname" 
#"math -mathlink" as default, which in general will open a new local 
Mathematica kernel.

In general, establishing a connection to a remote kernel requires 
two steps. First, the remote kernel must be started, then it must be 
instructed to establish a MathLink connection to MzScheme. Various 
MathLink commands can achieve the result.

1. Active Connection (LinkLaunch)
An active connection is initiated by using the MathLink function 
LinkLaunch["oscommands", options]. The argument oscommands is an 
operating system command that makes a connection to a remote machine 
and starts a Mathematica kernel on that remote machine. LinkLaunch[] 
is used by default for launching kernels on the local machine.

2. Callback Connection (LinkCreate)
For kernels on remote machines it is generally better to establish 
separate MathLink connections, rather than using the command channel 
opened by LinkLaunch. The host computer opens a MathLink link in 
Listen mode using LinkCreate[], then the remote kernel is instructed 
to connect to the listening link, usually by shell executing

ssh -f remotehost math -mathlink -linkmode Connect -linkname 
'linkspecification'

(where remotehost and linkspecification should be substitude with 
actual values) from the host computer.

3. Passive Connection (LinkConnect)
Active or callback connections may not be available because of 
operating system deficiencies or security measures. If this is the 
case, another method for establishing a connection is available. You 
can manually start a kernel on a remote machine and instruct it to 
open a TCPIP port on which to listen for connection requests. This 
is usually achieved by providing the command-line arguments 
-mathlink -linkcreate to the command to start the kernel, usually 
math. (Under Windows, add -linkprotocol TCPIP.) The started kernel 
will tell you the ports on which it is listening. In MzScheme you 
can make a connection to a listening kernel with the following 
command 

(MathKernel #"-linkconnect" #"-linkname" #"port1@hostname,port2@hostname")

(Under Windows, add #"-linkprotocol" #"TCPIP")

> MathEval : Mexp [MathLink] -> Mexp

Use Mathematica Kernel to evaluate. You should write the Mexp as a 
S-exp and they will be translated to Mathematica style automatical-
ly. Only number, boolean, symbol, string, void or none empty list of 
Mexp are recognized as Mexp.

The optional argment, MathLink, specifies using which Mathematica 
kernel to do the computation. If no MathLink is given, MrMathematica 
will use the current-mathlink, or if current-mathlink is #f, call 
(MathKernel) to create one.

> MathExit : [MathLink] -> void

Close the Mathematica Kernel. Please avoid using closed MathLink.

> MathLink? : exp -> boolean

Check whether the argument is a MathLink.

> current-mathlink

A parameter procedure that sets or retrieves the default MathLink to 
use. #f indicates no current MathLink. Each time MathKernel was 
called, the return value will be automatically set as current-
mathlink.

> frontend-mode

A parameter procedure that determines whether to work as a real 
Mathematica Front-End (which consumes more resource but support all 
Mathematica interaction, including Interrupt, Dialog, In/Out). The 
default value is #f.

> Mexp->image : Mexp [MathLink] -> image-snip%

Convert a Mexp to a image.

> $Display

A parameter procedure that determines whether to display Graphics 
from Mathematica Kernel as image in Scheme. The default value is #t.

_mma.ss_
--------

The same package for MzScheme in case MrEd is not available. It 
doesn't provide frontend-mode, Mexp->image and $Display.

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 it provides 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: 

SchemeLink
----------

An executatble named "SchemeLink" is installed in "plt" (or "plt/
bin"). It allows you to call PLT Scheme (including MrEd) from 
Mathematica.

To launch this program from within Mathematica use:
   In[1]:= link = Install["SchemeLink.exe"]

 Or, launch this program from a shell and establish a
 peer-to-peer connection.  When given the prompt Create Link:
 type a port name. ( On Unix platforms, a port name is a
 number less than 65536.  On Mac or Windows platforms,
 it's an arbitrary word.)
 Then, from within Mathematica use:
   In[1]:= link = Install["portname", LinkMode->Connect]

SchemeLink provide a Mathematica function Eval, which will evaluate 
it's argument in MzScheme.

The argument should be a valid Scheme expression, given in 
Mathematica. There is two way to do this: using S-exp or M-exp:

Eval[{car, {cons, 1, 2}}]
=>
1

Eval[cdr[cons[1, 2]]]
=>
2

In Mathematica, a symbol can contain any letters, letter-like 
forms, or digits, but cannot start with a digit. But in Scheme, a 
symbol can be composed from any characters. To address this 
problem, you can use SchemeSymbol["+"] to refer to the Scheme symbol 
+:

Eval[{SchemeSymbol["+"], 1, 2}]

Besides SchemeSymbol, there are SchemeImproperList, SchemeVector, 
SchemeBox, SchemeChar, SchemeBytes, SchemeTag, SchemeReference, 
SchemeHashTable, SchemeHashTableEq, SchemeRegExp, SchemePRegExp, 
and SchemeKeyword. Schemev[a,b,c,d] is interpreted as (a b c . d); 
SchemeVector[a,b,c,d] is interpreted as #(a b c d); Schemev[a] is 
interpreted as #&a; SchemeChar[,"c"] is interpreted as #\c; 
SchemeBytes["abcd"] is interpreted as #"abcd"; SchemeTag[n,exp] 
where n is a non-negative integer is interpreted as #n=exp; 
SchemeReference[n] where n is a non-negative integer is interpreted 
as #n#; SchemeHashTable is interpreted as #hash; SchemeHashTableEq 
is interpreted as #hasheq; SchemeRegExp is interpreted as #rx; 
SchemePRegExp is interpreted as #px; SchemeKeyword["abc"] is 
interpreted as #:"abc". Finally, SchemeExpression["a string"] is 
used to expression any Scheme expression as a string.

Mathematica's "Abort Evaluation" signal is converted to the Scheme's 
asynchronous break signal.

To unload Schemelink:
  Uninstall[link]