[BACK]Return to math2ox.texi CVS log [TXT][DIR] Up to [local] / OpenXM / src / ox_math / documents

Diff for /OpenXM/src/ox_math/documents/math2ox.texi between version 1.2 and 1.7

version 1.2, 2000/03/11 09:17:42 version 1.7, 2000/03/15 08:22:20
Line 1 
Line 1 
 %% $OpenXM: OpenXM/src/ox_math/documents/math2ox.texi,v 1.1 2000/03/08 06:59:37 ohara Exp $  %% $OpenXM: OpenXM/src/ox_math/documents/math2ox.texi,v 1.6 2000/03/14 14:59:39 ohara Exp $
   
 \input texinfo  \input texinfo
 @iftex  @iftex
Line 34 
Line 34 
 @node Top,, (dir), (dir)  @node Top,, (dir), (dir)
   
 @menu  @menu
   * Starting OX servers::
 * Mathematica Client Functions::  * Mathematica Client Functions::
 * Sample Programs::  * Sample Programs::
   * Example::
   * References::
 @end menu  @end menu
   
 @node Mathematica Client Functions,,, Top  @node Starting OX servers,,, Top
   @chapter Starting OX servers
   
 @chapter Mathematica Client Functions  @node Loading an OX Client on Mathematica,,, Starting OX servers
   @section Loading an OX Client on Mathematica
   
 The program @code{math2ox} is an external module for Mathematica  The program @code{math2ox} is an external module for Mathematica
 to call OpenXM servers.  to call OpenXM servers.
 The @code{math2ox} communicates with OpenXM servers by the OpenXM protocol  The @code{math2ox} communicates with OpenXM servers by the OpenXM protocol
 and communicates with Mathematica by MathLink.  and communicates with Mathematica by MathLink.
   
   In order to execute @code{math2ox}, you need to type as follows:
   @example
   In[1]:= Install["math2ox"]
   @end example
   
   We recommend loading a Mathematica program @code{oxclient.m} instead of
   calling @code{Install[]} directly:
   @example
   In[1] := <<oxclient.m
   @end example
   
   @node Starting OX servers on the localhost,,, Starting OX servers
   @section Starting OX servers on the localhost
   
 @c  Description of OxStart  @c  Description of OxStart
 @menu  @menu
 * OxStart::  * OxStart::
 @end menu  @end menu
   @node OxStart,,,
   @subsection @code{OxStart}
   @findex OxStart
   @table @t
   @item OxStart[@var{s}]
   ::  Start the OX server @code{s}.
   @end table
   
   @table @var
   @item return
   Integer
   @item s
   String
   @end table
   
   @itemize @bullet
   @item  It starts the OX server @code{s}.
   @item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
   @end itemize
   
   @example
   In[1]:= pid = OxStart["ox_sm1"]
   @end example
   
   In this example, @code{ox_sm1} is started on the local machine.
   
   @node Starting OX servers on a remote machine,,, Top
   @section Starting OX servers on a remote machine
   
   In order to connect to remote OX servers, it is convenient, secure and
   recommended to use @code{ssh} (Secure SHell).
   The function @code{OxStartRemoteSSH} starts remote OX servers
   by ssh.  Of course, you are supposed to be able to login the remote
   machine by @code{ssh} and @code{$Remote_OpenXM_HOME/rc/cshrc} or
   @code{$Remote_OpenXM_HOME/rc/bashrc} are executed from the login shell
   of your remote machine.
   The function @code{OxStartRemoteSSH[]} does not request your password,
   that is, you need to be using @code{ssh-agent} before calling
   @code{OxStartRemoteSSH[]}.
   Then there will be no check of password.
   
   @node Starting the X Window System with ssh-agent,,, Starting OX servers on a remote machine
   @subsection Starting the X Window System with ssh-agent
   
   If you use the @code{startx} command to boot the X Window System, then
   we recommend you replace the command by @code{ssh-agent startx}.
   @example
   bash$ ssh-agent startx
   @end example
   If you use @code{xdm} program to login your machine,
   then your @code{.xsession} script needs to contain the followings:
   @example
   exec ssh-agent .xinitrc
   @end example
   @noindent
   where @code{.xinitrc} is executable.
   
   After booting the X Window System, you need to type on suitable terminal
   emulator as follows:
   @example
   bash$ ssh-add
   @end example
   @noindent
   and input your passphrase.
   
   See ssh(1), ssh-agent(1), ssh-add(1), and ssh-keygen(1) for detail.
   
   @c  Description of OxStartRemoteSSH
   @menu
   * OxStartRemoteSSH::
   @end menu
   @node OxStartRemoteSSH,,,
   @subsection @code{OxStartRemoteSSH}
   @findex OxStartRemoteSSH
   @table @t
   @item OxStartRemoteSSH[@var{s}, @var{host}]
   ::  start the OX server @code{s} on the remote machine @code{host} by ssh.
   @end table
   
   @table @var
   @item return
   Integer
   @item s
   String
   @item host
   String
   @end table
   
   We note that the @code{OxStartRemoteSSH[]} is an experimental implementation.
   
   @itemize @bullet
   @item  It starts the OX server @code{s}.
   @item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
   @end itemize
   
   @example
   In[1]:= pid = OxStartRemoteSSH["ox_sm1", "remotehost"]
   @end example
   
   In this example, @code{ox_sm1} is started on the remote machine @code{remotehost}.
   
   @node Mathematica Client Functions,,, Top
   @chapter Mathematica Client Functions
   
   @c  Description of OxStart
   @menu
   * OxStart::
   @end menu
 @node OxStart,,, Mathematica Client Functions  @node OxStart,,, Mathematica Client Functions
 @section @code{OxStart}  @section @code{OxStart}
 @findex OxStart  @findex OxStart
Line 68  String
Line 195  String
   
 @itemize @bullet  @itemize @bullet
 @item  It starts the OX server @code{s}.  @item  It starts the OX server @code{s}.
 @item Servers are looked for in the directory $OenXM_HOME/bin , hoge hoge.  @item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
 @end itemize  @end itemize
   
 @example  @example
 In[1]:= Install["math2ox"]  In[1]:= pid = OxStart["ox_sm1"]
 In[2]:= pid = OxStart["ox_sm1"]  
 @end example  @end example
   
 In this example, @code{ox_sm1} is started on the local machine.  In this example, @code{ox_sm1} is started on the local machine.
Line 87  In this example, @code{ox_sm1} is started on the local
Line 213  In this example, @code{ox_sm1} is started on the local
 @findex OxSendMessage  @findex OxSendMessage
 @table @t  @table @t
 @item OxSendMessage[@var{pid}, @var{s}]  @item OxSendMessage[@var{pid}, @var{s}]
 ::  SendMessage @code{s} to the OX server @code{pid}.  ::  send a message @code{s} to the OX server @code{pid}.
 @end table  @end table
   
 @table @var  @table @var
 @item return  @item return
 Integer  Integer
 @item id  @item pid
 Integer  Integer
 @item s  @item s
 String  String
 @end table  @end table
   
 @itemize @bullet  
 @item  It starts the OX server @code{s}.  
 @item Servers are looked for in the directory $OenXM_HOME/bin , hoge hoge.  
 @end itemize  
   
 @example  @example
 In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]  In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
 In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]  In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
Line 114  In this example, an OX data message 
Line 235  In this example, an OX data message 
 and an OX command message (OX_COMMAND, (SM_popCMO)) are sent to  and an OX command message (OX_COMMAND, (SM_popCMO)) are sent to
 the OX server @code{pid}.  the OX server @code{pid}.
   
 @c  Put descriptions of a next function.  @c  Description of OxPopCMO
   @menu
   * OxPopCMO::
   @end menu
   @node OxPopCMO,,, Mathematica Client Functions
   @section @code{OxPopCMO}
   @findex OxPopCMO
   @table @t
   @item OxPopCMO[@var{pid}]
   ::  pop an object on the top of the stack.
   @end table
   
   @table @var
   @item return
   Manual
   @item pid
   Integer
   @end table
   
 @node Starting OX servers on a remote machines,,, Top  The @code{OxPopCMO[]} function pops an object on the top of the stack of
 @chapter Starting OX servers on a remote machines  the OX stack machine @code{pid} and returns the object.
   The return type of the function @code{OxPopCMO[]} is @code{Manual} in
   terms of MathLink, that is, an object of suitable type is returned.
   
   @example
   In[5] := cmo = OxPopCMO[pid]
   @end example
   
   @c  Description of OxPopString
   @menu
   * OxPopString::
   @end menu
   @node OxPopString,,, Mathematica Client Functions
   @section @code{OxPopString}
   @findex OxPopString
   @table @t
   @item OxPopString[@var{pid}]
   ::  get a string from the OX server @code{pid}.
   @end table
   
   @table @var
   @item return
   String
   @item pid
   Integer
   @end table
   
   The @code{OxPopString[]} function pops an object on the top of the stack
   of the OX stack machine @code{pid} and returns a string which is
   translated from the object by the OX stack machine.
   
   @example
   In[5] := string = OxPopString[pid]
   @end example
   
   @c  Description of OxClose
   @menu
   * OxClose::
   @end menu
   @node OxClose,,, Mathematica Client Functions
   @section @code{OxClose}
   @findex OxClose
   @table @t
   @item OxClose[@var{pid}]
   ::  close the connection to the OX server @code{pid}.
   @end table
   
   @table @var
   @item return
   none
   @item pid
   Integer
   @end table
   
   The @code{OxClose[]} function closes the connection to the OX server
   @code{pid}.
   
   @example
   In[5] := OxClose[pid]
   @end example
   
   @c  Description of OxExecuteString
   @menu
   * OxExecuteString::
   @end menu
   @node OxExecuteString,,, Mathematica Client Functions
   @section @code{OxExecuteString}
   @findex OxExecuteString
   @table @t
   @item OxExecuteString[@var{pid}, @var{command}]
   ::  execute @code{command} on the OX server @code{pid}.
   @end table
   
   @table @var
   @item return
   none
   @item pid
   Integer
   @item command
   String
   @end table
   
   The @code{OxExecuteString[]} function executes @code{command} on the OX server
   @code{pid}.
   The string @code{command} is interpreted in local language of the OX server.
   
   @example
   In[5] := OxExecuteString["print(1+2);"]
   @end example
   
   @c  Description of OxGet
   @menu
   * OxGet::
   @end menu
   @node OxGet,,, Mathematica Client Functions
   @section @code{OxGet}
   @findex OxGet
   @table @t
   @item OxGet[@var{pid}]
   ::  get an object from the connection to the OX server @code{pid}.
   @end table
   
   @table @var
   @item return
   Manual
   @item pid
   Integer
   @end table
   
   The @code{OxGet[]} function gets an object from the connection to the OX server
   @code{pid}.
   
   @example
   In[5] := cmo = OxGet[pid]
   @end example
   
   @c  Put descriptions of a next function.
   
 @node Sample Programs,,, Top  @node Sample Programs,,, Top
 @chapter Sample Programs  @chapter Sample Programs
   
 @tex  @enumerate
 \noindent  @item
 1.  @code{OpenXM/lib/math/oxclient.m} is a Mathematica program
 {\tt OpenXM/lib/math/primadec.m} is a Mathematica program  to load the @code{math2ox} and to define some Mathematica
   functions for @code{primadec.m} and @code{beta.m}.
   
   @item
   @code{OpenXM/lib/math/primadec.m} is a Mathematica program
 to make primary ideal decompositions by calling  to make primary ideal decompositions by calling
 {\tt ox\_asir}.  @code{ox_asir}.
 As to usages, see comments in this file.  As to usages, see comments in this file.
   
 \noindent 2.  @item
 {\tt OpenXM/lib/math/beta.m} is a Mathematica program  @code{OpenXM/lib/math/beta.m} is a Mathematica program
 to get beta-nbc bases by calling {\tt ox\_asir}.  to get beta-nbc bases by calling @code{ox_asir}.
 @end tex  @end enumerate
   
   @node Example,,, Top
   @chapter Example
   
   The @code{math2ox} has the following commands:
   
   @code{OxStart[],
   OxStartInsecure[],
   OxStartRemoteSSH[],
   OxExecuteString[],
   OxSendMessage[],
   OxGet[],
   OxPopCMO[],
   OxPopString[],
   OxClose[],
   OxReset[]}.
   
   First, let us load the math2ox.
   @example
   In[1]:= <<oxclient.m
   @end example
   
   Second, let us open a connection with an OX server.
   For example, if we want to call the @code{ox_sm1} (the kan/sm1 server), then
   @example
   In[2] := pid = OxStart["ox_sm1"]
   @end example
   @noindent
   where we have the connection of reverse mode.  The @code{OxStart}
   function automatically invoke @code{ox_sm1} on the localhost.
   If you need to connect remote OX servers, then you can use reverse mode.
   @example
   In[2] := pid = OxStartRemoteSSH["ox_sm1", "orange.math.kobe-u.ac.jp"]
   @end example
   
   @c  Remarks: old version.
   @c  @example
   @c  In[2] := pid = OxStartInsecure["water.s.kanazawa-u.ac.jp", 1300, 1400]
   @c  @end example
   @c  The mode is not secured but you can crypt data stream by using ssh
   @c  (Secure SHell).
   @c  @example
   @c  In[3] := Run["ssh -f water ox -insecure -ox ox_sm1 -host water"]
   @c  @end example
   
   Third, let us send an OX message to the OX server.
   We can send an OX message written in OX/CMO expressions.
   @example
   In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
   @end example
   @noindent
   If the expression contains syntax errors, then nothing is sent.
   
   If you need to get the object on the top of the stack of an OX server
   @code{pid}, then you can call the following function:
   @example
   In[5] := cmo = OxPopCMO[pid]
   @end example
   
   The function @code{OxPopCMO} above is equivalent to
   the following two command:
   @example
   In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
   In[6] := cmo = OxGet[pid]
   @end example
   
   Remarks:
   if @code{SM_popCMO} is sent by the @code{OxSendMessage[]} function, then
   the OX stack machine returns the top of the stack to the @code{math2ox}.
   Then, in order to receive the message, we need to call the
   @code{OxGet[]} function always after executing @code{OxSendMessage[]}.
   That is @code{OxGet} flushes the communication route to @code{pid}.  If
   we never use the @code{OxSendMessage} function, then we do not need to
   call the @code{OxGet[]}.
   
   Fourth, if we send a command expressed in the local language of the OX
   server, then we need to call the @code{OxExecuteString[]} function.
   
   Last, let us close the connection.
   @example
   In[7] := OxClose[pid]
   @end example
   
   @c @node Bibliography,,, Top
   @c @unnumbered Bibliography
   @node References,,, Top
   @unnumbered References
   
   @enumerate
   @item
   M. Noro, N. Takayama:
   Design and Implementation of OpenXM, 1996, 1997, 1998, 1999, 2000.
   
   @item
   @code{http://www.math.kobe-u.ac.jp/OpenXM/}
   
   @item
   M. Noro, K. Ohara, N. Takayama:
   {Introduction to Open Asir}, 1999, Suusiki Shori, Vol 7, No 2,
   2--17. (ISBN4-87243-086-7, SEG Publishing, Tokyo). (in Japanese)
   
   @item
   Stephen Wolfram:
   {The Mathematica Book}, Third edition,
   Wolfram Media/Cambridge University Press, 1996.
   
   @item
   T. Miyachi:
   {Mathematica Network Programming},
   Iwanami Shoten Publishers, 1998. (in Japanese)
   @end enumerate
   
 @node Index,,, Top  @node Index,,, Top
 @unnumbered Index  @unnumbered Index
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.7
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>