From: Ulrich Pfeifer <[email protected]>
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules
Subject: ANNOUNCE: Math::ematica 1.106 - Perl talks to Mathematica talks to Perl
Followup-To: comp.lang.perl.modules
Date: 27 Feb 1998 16:08:31 GMT
Organization: WAIT - Wide Area Information Systems
Lines: 277
Sender: [email protected]
Approved: [email protected] (comp.lang.perl.announce)
Message-ID: <[email protected]>
References: <[email protected]>, <[email protected]>
NNTP-Posting-Host: gadget.cscaper.com
X-Disclaimer: The "Approved" header verifies header information for article transmission and does not imply approval of content.
Path: usenet.cise.ufl.edu!huron.eel.ufl.edu!usenet.eel.ufl.edu!nntp1.jpl.nasa.gov!news.spies.com!news.sgi.com!nntprelay.mathworks.com!news-xfer.netaxs.com!nac!nntp.teleport.com!news.teleport.com!not-for-mail
Xref: usenet.cise.ufl.edu comp.lang.perl.announce:85 comp.lang.perl.modules:2282

New in 1.106:

       Calling Perl from a running Mathematica session (calling back
       from a spawned sub-kernel was possible before).

http://www.perl.com/CPAN/authors/id/ULPFR/

Ulrich Pfeifer
--
NAME
   Math::ematica - Perl extension for connecting Mathematica(TM)

SYNOPSIS
     use Math::ematica qw(:PACKET :TYPE :FUNC);

WARNING
   This is alpha software. User visible changes can happen any time.

   The module is completely rewritten. Literally no line of the old stuff
   is used (don't ask - I've learned a few things since these days ;-). If
   you are using the old 1.006 version, note that the interface has
   changed. If there is an overwhelming outcry, I will provide some
   backward compatibility stuff.

   Feel free to suggest modifications and/or extensions. I don not use
   Mathematica for real work right now and may fail to foresee the most
   urgent needs. Even if you think that the interface is great, you are
   invited to complete the documentation (and fix grammos and typos). Since
   I am no native English speaker, I will delay the writing of real
   documentation until the API has stabilized.

   I do develop this module using Mathematica 3.0.1 on a Linux 2.0.30 box.
   Let me know, if it does work with other versions of Mathematica or does
   not work on other *nix flavors.

DESCRIPTION
   The `Math::ematica' module provides an interface to the MathLink(TM)
   library. Functions are not exported and should be called as methods.
   Therefore the Perl names have the 'ML' prefix stripped. Since Perl can
   handle multiple return values, methods fetching elements from the link
   return the values instead of passing results in reference parameters.

   The representation of the data passed between Perl and Mathematica is
   straight forward exept the symbols which are represented as blessed
   scalars in Perl.

Exported constants
   `PACKET'
        The `PACKET' tag identifies constants used as packet types.

          print "Got result packet" if $link->NextPacket == RETURNPKT;

   `TYPE'
        The `TYPE' tag identifies constants used as elements types.

          print "Got a symbol" if $link->GetNext == MLTKSYM;

Exported functions
   `FUNC'
        The `FUNC' tag currently only contains the `symbol' function which
        returns the symbol for a given name.

          $sym = symbol 'Sin';

The plain interface
   This set of methods gives you direct access to the MathLink function.
   Don't despair if you don't know them too much. There is a convenient
   layer ontop of them ;-). Methods below are only commented if they do
   behave different than the corresponding C functions. Look in your
   MathLink manual for details.

 `new'

   The constructor is just a wrapper around `MLOpenArgv'.

     $ml = new Math::ematica '-linklaunch', '-linkname', 'math -mathlink';

   The link is automatically activated on creation and will be closed upon
   destruction.

 `ErrorMessage'

     print $link->ErrorMessage;

 `EndPacket'

 `Flush'

 `NewPacket'

 `NextPacket'

 `Ready'

 `PutSymbol'

 `PutString'

 `PutInteger'

 `PutDouble'

 `PutFunction'

 `GetNext'

 `GetInteger'

 `GetDouble'

 `GetString'

   The method does the appropriate `MLDisownString' call for you.

 `GetSymbol'

   The module does the appropriate `MLDisownSymbol' call for you. It also
   blesses the result string into the package `Math::ematica::symbol'.

 `Function'

   Returns the function name and argument count in list context. In scalar
   contex only the function name is returned.

 `GetRealList'

   Returns the array of reals.

The convenience interface
 `PutToken'

   Puts a single token according to the passed data type.

     $link->PutToken(1);               # MLPutInteger

   Symbols are translated to `MLPutFunction' if the arity is provided as
   aditional parameter.

     $link->PutToken(symbol 'Pi');     # MLPutSymbol
     $link->PutToken(symbol 'Sin', 1); # MLPutFunction

 `read_packet'

   Reads the current packet and returns it as nested data structure. The
   implementaion is not complete. But any packet made up of `MLTKREAL',
   `MLTKINT', `MLTKSTR', `MLTKSYM', and `MLTKFUNC' should translate
   correctely. A function symbol `List' is dropped automatically. So the
   Mathematica expression `List[1,2,3]' translates to the Perl expression
   `[1,2,3]'.

   *Mabybe this is *too* convenient?*.

 `call'

   Call is the main convenience interface. You will be able to do most if
   not all using this call.

   Note that the syntax is nearly the same as you are used to as *FullForm*
   in Mathematica. Only the function names are moved inside the brackets
   and separated with ',' from the arguments. The method returns the nested
   data structures read by `read_packet'.

     $link->call([symbol 'Sin', 3.14159265358979/2]); # returns something near 1

   To get a table of values use:

     $link->call([symbol 'Table',
                  [symbol 'Sin', symbol 'x'],
                  [symbol 'List', symbol 'x',  0, 1, 0.1]]);

   This returns a reference to an array of doubles.

   You may omit the first `symbol'. *Maybe we should choose the default
   mapping to *Symbol* an require *Strings*s to be marked?*

 `install'

   If you find this too ugly, you may `install' Mathematica functions as
   Perl functions using the `install' method.

     $link->install('Sin',1);
     $link->install('Pi');
     $link->install('N',1);
     $link->install('Divide',2);

     Sin(Divide(Pi(),2.0)) # should return 1 (on machines which can
                           # represent '2.0' *exactely* in a double ;-)

   The `install' method takes the name of the mathematica function, the
   number of arguments and optional the name of the Perl function as
   argument.

     $link->install('Sin',1,'sin_by_mathematica');

   Make shure that you do not call any *installed* function after the
   `$link' has gone. Wild things will happen!

 `send_packet'

   Is the sending part of `call'. It translates the expressions passed to a
   Mathematica package and puts it on the link.

 `register'

   This method allows to register your Perl functions to Mathematica.
   *Registered* functions may be called during calculations.

     sub addtwo {
       $_[0]+$_[1];
     }

     $link->register('AddTwo', \&addtwo, 'Integer', 'Integer');
     $link->call([symbol 'AddTwo',12, 3]) # returns 15

   You may register functions with unspecified argument types using undef:

     sub do_print {
       print @_;
     }
     $link->register('DoPrint', undef);
     $link->call(['DoPrint',12]);
     $link->call(['DoPrint',"Hello"]);

 `main'

   This method allows to have Perl scripts installed in a running
   Mathematica session. The Perl script try.pl might look like this:

     use Math::ematica;
     sub addtwo {
       my ($x, $y) = @_;

       $x + $y;
     }
     $ml->register('AddTwo', \&addtwo, 'Integer', 'Integer');
     $ml->main;

   Inside the Mathematica do:

     Install["try.pl"]
     AddTwo[3,5];

   Admittedly, adding two numbers would be easier inside Mathematica. But
   how about DNS lookups querying or SQL Databases?

AUTHOR
   Ulrich Pfeifer <[email protected]>

SEE ALSO
   See also the perl(1) manpage and your Mathematica and MathLink
   documentation. Also check the t/*.t files in the distribution.

ACKNOWLEDGEMENTS
   I wish to thank Jon Orwant of *The Perl Journal*, Nancy Blachman from
   *The Mathematica Journal* and Brett H. Barnhart from *Wolfram Research*.

   Jon brought the earlier versions of this module to the attention of
   Nancy Blachman. She in turn did contact Brett H. Barnhart who was so
   kind to provide a trial license which made this work possible.

   So subscribe to *The Perl Journal* and *The Mathematica Journal* if you
   are not subscribed already if you use this module (a Mathematica license
   is needed anyway). You would be nice to nice people and may even read
   something more about this module one day ;-)

   Special thanks to Randal L. Schwartz for naming this module.

Copyright
   The Math:ematica module is Copyright (c) 1996,1997,1998 Ulrich Pfeifer.
   Germany. All rights reserved.

   You may distribute under the terms of either the GNU General Public
   License or the Artistic License, as specified in the Perl README file.

   Mathematica and MathLink are registered trademarks of Wolfram Research.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.