Annotation of OpenXM/src/ox_math/documents/math2ox.texi, Revision 1.8
1.8 ! ohara 1: %% $OpenXM: OpenXM/src/ox_math/documents/math2ox.texi,v 1.7 2000/03/15 08:22:20 ohara Exp $
1.1 ohara 2:
3: \input texinfo
4: @iftex
5: @catcode`@#=6
6: @def@b#1{{@bf@gt #1}}
7: @catcode`@#=@other
8: @end iftex
9: @overfullrule=0pt
10: @c -*-texinfo-*-
11: @comment %**start of header
12: @setfilename Math2ox
13: @settitle Math2ox
14: @comment %**end of header
15: @comment %@setchapternewpage odd
16:
17: @iftex
18: @comment @finalout
19: @end iftex
20:
21: @titlepage
22:
23: @title Math2ox
24: @subtitle Math2ox User's Manual (English Edition)
25: @subtitle Edition 1.1.2 for OpenXM/oxmath
26: @subtitle March 2000
27:
28: @author by Katsuyoshi Ohara
29: @end titlepage
30:
31: @synindex vr fn
32:
33: @comment node-name, next, previous, up
34: @node Top,, (dir), (dir)
35:
36: @menu
1.6 ohara 37: * Starting OX servers::
1.1 ohara 38: * Mathematica Client Functions::
39: * Sample Programs::
1.6 ohara 40: * Example::
41: * References::
1.1 ohara 42: @end menu
43:
1.3 ohara 44: @node Starting OX servers,,, Top
1.6 ohara 45: @chapter Starting OX servers
46:
47: @node Loading an OX Client on Mathematica,,, Starting OX servers
48: @section Loading an OX Client on Mathematica
49:
50: The program @code{math2ox} is an external module for Mathematica
51: to call OpenXM servers.
52: The @code{math2ox} communicates with OpenXM servers by the OpenXM protocol
53: and communicates with Mathematica by MathLink.
1.3 ohara 54:
1.7 ohara 55: In order to execute @code{math2ox}, you need to type as follows:
1.6 ohara 56: @example
57: In[1]:= Install["math2ox"]
58: @end example
59:
1.8 ! ohara 60: The Mathematica program oxclient.m, which is used to load math2ox
! 61: and set some global variables, is in the directory
! 62: @code{$OpenXM_HOME/lib/oxmath}.
! 63: The standard value of @code{$OpenXM_HOME} is @code{/usr/local/OpenXM}.
! 64: We recommend using @code{oxclient.m} instead of @code{Install[]}:
1.6 ohara 65: @example
66: In[1] := <<oxclient.m
67: @end example
1.3 ohara 68:
69: @node Starting OX servers on the localhost,,, Starting OX servers
70: @section Starting OX servers on the localhost
71:
72: @c Description of OxStart
73: @menu
74: * OxStart::
75: @end menu
76: @node OxStart,,,
77: @subsection @code{OxStart}
78: @findex OxStart
79: @table @t
80: @item OxStart[@var{s}]
81: :: Start the OX server @code{s}.
82: @end table
83:
84: @table @var
85: @item return
86: Integer
87: @item s
88: String
89: @end table
90:
91: @itemize @bullet
92: @item It starts the OX server @code{s}.
1.4 ohara 93: @item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
1.3 ohara 94: @end itemize
95:
96: @example
1.6 ohara 97: In[1]:= pid = OxStart["ox_sm1"]
1.3 ohara 98: @end example
99:
100: In this example, @code{ox_sm1} is started on the local machine.
101:
102: @node Starting OX servers on a remote machine,,, Top
103: @section Starting OX servers on a remote machine
104:
1.4 ohara 105: In order to connect to remote OX servers, it is convenient, secure and
106: recommended to use @code{ssh} (Secure SHell).
107: The function @code{OxStartRemoteSSH} starts remote OX servers
108: by ssh. Of course, you are supposed to be able to login the remote
109: machine by @code{ssh} and @code{$Remote_OpenXM_HOME/rc/cshrc} or
110: @code{$Remote_OpenXM_HOME/rc/bashrc} are executed from the login shell
111: of your remote machine.
1.8 ! ohara 112: The function @code{OxStartRemoteSSH[]} does not ask your password,
1.4 ohara 113: that is, you need to be using @code{ssh-agent} before calling
114: @code{OxStartRemoteSSH[]}.
115: Then there will be no check of password.
1.3 ohara 116:
1.7 ohara 117: @node Starting the X Window System with ssh-agent,,, Starting OX servers on a remote machine
118: @subsection Starting the X Window System with ssh-agent
119:
1.8 ! ohara 120: In this subsection, we will explain how to start ssh-agent
! 121: and set your password by ssh-add
! 122: for reader's convinience. As to details, see ssh-agent (1)
! 123: and ssh-add (1).
! 124: If you start the X-windows system by @code{startx}, you can start
! 125: ssh-agent by @code{ssh-agent startx}.
! 126:
1.7 ohara 127: @example
128: bash$ ssh-agent startx
129: @end example
130: If you use @code{xdm} program to login your machine,
131: then your @code{.xsession} script needs to contain the followings:
132: @example
133: exec ssh-agent .xinitrc
134: @end example
135: @noindent
136: where @code{.xinitrc} is executable.
137:
1.8 ! ohara 138: After starting the X Window System, you need to type on suitable terminal
1.7 ohara 139: emulator as follows:
140: @example
141: bash$ ssh-add
142: @end example
143: @noindent
1.8 ! ohara 144: and input your passphrase. Once you set your passphrase by ssh-add, you
! 145: no longer need to input your passphrase to access to other machines by
! 146: ssh.
1.7 ohara 147:
1.3 ohara 148: @c Description of OxStartRemoteSSH
149: @menu
150: * OxStartRemoteSSH::
151: @end menu
152: @node OxStartRemoteSSH,,,
153: @subsection @code{OxStartRemoteSSH}
154: @findex OxStartRemoteSSH
155: @table @t
156: @item OxStartRemoteSSH[@var{s}, @var{host}]
1.4 ohara 157: :: start the OX server @code{s} on the remote machine @code{host} by ssh.
1.3 ohara 158: @end table
159:
160: @table @var
161: @item return
162: Integer
163: @item s
164: String
165: @item host
166: String
167: @end table
168:
1.4 ohara 169: We note that the @code{OxStartRemoteSSH[]} is an experimental implementation.
1.3 ohara 170:
171: @itemize @bullet
172: @item It starts the OX server @code{s}.
1.4 ohara 173: @item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
1.3 ohara 174: @end itemize
175:
176: @example
1.6 ohara 177: In[1]:= pid = OxStartRemoteSSH["ox_sm1", "remotehost"]
1.3 ohara 178: @end example
179:
180: In this example, @code{ox_sm1} is started on the remote machine @code{remotehost}.
181:
1.1 ohara 182: @node Mathematica Client Functions,,, Top
183: @chapter Mathematica Client Functions
184:
185: @c Description of OxStart
186: @menu
187: * OxStart::
188: @end menu
189: @node OxStart,,, Mathematica Client Functions
190: @section @code{OxStart}
191: @findex OxStart
192: @table @t
1.2 ohara 193: @item OxStart[@var{s}]
1.1 ohara 194: :: Start the OX server @code{s}.
195: @end table
196:
197: @table @var
198: @item return
199: Integer
200: @item s
201: String
202: @end table
203:
204: @itemize @bullet
205: @item It starts the OX server @code{s}.
1.4 ohara 206: @item Servers are looked for in the directory $OpenXM_HOME/bin, hoge hoge.
1.1 ohara 207: @end itemize
208:
209: @example
1.6 ohara 210: In[1]:= pid = OxStart["ox_sm1"]
1.1 ohara 211: @end example
212:
213: In this example, @code{ox_sm1} is started on the local machine.
214:
1.2 ohara 215: @c Description of OxSendMessage
216: @menu
217: * OxSendMessage::
218: @end menu
219: @node OxSendMessage,,, Mathematica Client Functions
220: @section @code{OxSendMessage}
221: @findex OxSendMessage
222: @table @t
223: @item OxSendMessage[@var{pid}, @var{s}]
1.3 ohara 224: :: send a message @code{s} to the OX server @code{pid}.
1.2 ohara 225: @end table
226:
227: @table @var
228: @item return
229: Integer
1.3 ohara 230: @item pid
1.2 ohara 231: Integer
232: @item s
233: String
234: @end table
235:
236: @example
237: In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
238: In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
239: @end example
240:
241: In this example, an OX data message
242: (OX_DATA, (CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))
243: and an OX command message (OX_COMMAND, (SM_popCMO)) are sent to
244: the OX server @code{pid}.
245:
1.3 ohara 246: @c Description of OxPopCMO
247: @menu
248: * OxPopCMO::
249: @end menu
250: @node OxPopCMO,,, Mathematica Client Functions
251: @section @code{OxPopCMO}
252: @findex OxPopCMO
253: @table @t
254: @item OxPopCMO[@var{pid}]
255: :: pop an object on the top of the stack.
256: @end table
257:
258: @table @var
259: @item return
260: Manual
261: @item pid
262: Integer
263: @end table
264:
1.4 ohara 265: The @code{OxPopCMO[]} function pops an object on the top of the stack of
1.3 ohara 266: the OX stack machine @code{pid} and returns the object.
1.4 ohara 267: The return type of the function @code{OxPopCMO[]} is @code{Manual} in
268: terms of MathLink, that is, an object of suitable type is returned.
1.3 ohara 269:
270: @example
1.4 ohara 271: In[5] := cmo = OxPopCMO[pid]
1.3 ohara 272: @end example
273:
274: @c Description of OxPopString
275: @menu
276: * OxPopString::
277: @end menu
278: @node OxPopString,,, Mathematica Client Functions
279: @section @code{OxPopString}
280: @findex OxPopString
281: @table @t
282: @item OxPopString[@var{pid}]
283: :: get a string from the OX server @code{pid}.
284: @end table
285:
286: @table @var
287: @item return
288: String
289: @item pid
290: Integer
291: @end table
292:
1.4 ohara 293: The @code{OxPopString[]} function pops an object on the top of the stack
1.3 ohara 294: of the OX stack machine @code{pid} and returns a string which is
1.4 ohara 295: translated from the object by the OX stack machine.
1.3 ohara 296:
297: @example
1.4 ohara 298: In[5] := string = OxPopString[pid]
1.3 ohara 299: @end example
300:
301: @c Description of OxClose
302: @menu
303: * OxClose::
304: @end menu
305: @node OxClose,,, Mathematica Client Functions
306: @section @code{OxClose}
307: @findex OxClose
308: @table @t
309: @item OxClose[@var{pid}]
310: :: close the connection to the OX server @code{pid}.
311: @end table
312:
313: @table @var
314: @item return
315: none
316: @item pid
317: Integer
318: @end table
319:
1.4 ohara 320: The @code{OxClose[]} function closes the connection to the OX server
1.3 ohara 321: @code{pid}.
322:
323: @example
1.4 ohara 324: In[5] := OxClose[pid]
1.3 ohara 325: @end example
326:
327: @c Description of OxExecuteString
328: @menu
329: * OxExecuteString::
330: @end menu
331: @node OxExecuteString,,, Mathematica Client Functions
332: @section @code{OxExecuteString}
333: @findex OxExecuteString
334: @table @t
335: @item OxExecuteString[@var{pid}, @var{command}]
336: :: execute @code{command} on the OX server @code{pid}.
337: @end table
338:
339: @table @var
340: @item return
341: none
342: @item pid
343: Integer
344: @item command
345: String
346: @end table
347:
348: The @code{OxExecuteString[]} function executes @code{command} on the OX server
349: @code{pid}.
1.4 ohara 350: The string @code{command} is interpreted in local language of the OX server.
1.3 ohara 351:
352: @example
353: In[5] := OxExecuteString["print(1+2);"]
354: @end example
355:
356: @c Description of OxGet
357: @menu
358: * OxGet::
359: @end menu
360: @node OxGet,,, Mathematica Client Functions
361: @section @code{OxGet}
362: @findex OxGet
363: @table @t
364: @item OxGet[@var{pid}]
365: :: get an object from the connection to the OX server @code{pid}.
366: @end table
367:
368: @table @var
369: @item return
370: Manual
371: @item pid
372: Integer
373: @end table
374:
1.4 ohara 375: The @code{OxGet[]} function gets an object from the connection to the OX server
1.3 ohara 376: @code{pid}.
1.1 ohara 377:
1.3 ohara 378: @example
1.4 ohara 379: In[5] := cmo = OxGet[pid]
1.3 ohara 380: @end example
1.2 ohara 381:
1.3 ohara 382: @c Put descriptions of a next function.
1.1 ohara 383:
384: @node Sample Programs,,, Top
385: @chapter Sample Programs
386:
1.5 ohara 387: @enumerate
388: @item
1.7 ohara 389: @code{OpenXM/lib/math/oxclient.m} is a Mathematica program
390: to load the @code{math2ox} and to define some Mathematica
391: functions for @code{primadec.m} and @code{beta.m}.
392:
393: @item
1.5 ohara 394: @code{OpenXM/lib/math/primadec.m} is a Mathematica program
1.1 ohara 395: to make primary ideal decompositions by calling
1.5 ohara 396: @code{ox_asir}.
1.1 ohara 397: As to usages, see comments in this file.
398:
1.5 ohara 399: @item
400: @code{OpenXM/lib/math/beta.m} is a Mathematica program
401: to get beta-nbc bases by calling @code{ox_asir}.
402: @end enumerate
403:
404: @node Example,,, Top
405: @chapter Example
406:
1.8 ! ohara 407: In this section, we will present a simple OpenXM session
! 408: on Mathematica to send a list
! 409: @example
! 410: ["Hello World", 0]
! 411: @end example
! 412: @noindent
! 413: to a server and pops that list from the server.
! 414:
1.5 ohara 415: The @code{math2ox} has the following commands:
416:
1.7 ohara 417: @code{OxStart[],
418: OxStartInsecure[],
419: OxStartRemoteSSH[],
420: OxExecuteString[],
421: OxSendMessage[],
422: OxGet[],
423: OxPopCMO[],
424: OxPopString[],
425: OxClose[],
426: OxReset[]}.
1.1 ohara 427:
1.8 ! ohara 428: First, let us load the @code{math2ox}.
1.5 ohara 429: @example
430: In[1]:= <<oxclient.m
431: @end example
432:
433: Second, let us open a connection with an OX server.
434: For example, if we want to call the @code{ox_sm1} (the kan/sm1 server), then
435: @example
1.7 ohara 436: In[2] := pid = OxStart["ox_sm1"]
1.5 ohara 437: @end example
1.7 ohara 438: @noindent
439: where we have the connection of reverse mode. The @code{OxStart}
440: function automatically invoke @code{ox_sm1} on the localhost.
441: If you need to connect remote OX servers, then you can use reverse mode.
442: @example
443: In[2] := pid = OxStartRemoteSSH["ox_sm1", "orange.math.kobe-u.ac.jp"]
444: @end example
445:
446: @c Remarks: old version.
447: @c @example
448: @c In[2] := pid = OxStartInsecure["water.s.kanazawa-u.ac.jp", 1300, 1400]
449: @c @end example
450: @c The mode is not secured but you can crypt data stream by using ssh
451: @c (Secure SHell).
452: @c @example
453: @c In[3] := Run["ssh -f water ox -insecure -ox ox_sm1 -host water"]
454: @c @end example
1.5 ohara 455:
456: Third, let us send an OX message to the OX server.
457: We can send an OX message written in OX/CMO expressions.
458: @example
459: In[4] := OxSendMessage[pid, "(CMO_LIST, (CMO_STRING, "hello world"), (CMO_ZERO))"]
460: @end example
1.7 ohara 461: @noindent
1.6 ohara 462: If the expression contains syntax errors, then nothing is sent.
1.5 ohara 463:
1.7 ohara 464: If you need to get the object on the top of the stack of an OX server
465: @code{pid}, then you can call the following function:
1.5 ohara 466: @example
1.7 ohara 467: In[5] := cmo = OxPopCMO[pid]
1.5 ohara 468: @end example
469:
1.7 ohara 470: The function @code{OxPopCMO} above is equivalent to
471: the following two command:
1.5 ohara 472: @example
1.7 ohara 473: In[5] := OxSendMessage[pid, "(OX_COMMAND, (SM_popCMO))"]
474: In[6] := cmo = OxGet[pid]
1.5 ohara 475: @end example
1.7 ohara 476:
477: Remarks:
478: if @code{SM_popCMO} is sent by the @code{OxSendMessage[]} function, then
479: the OX stack machine returns the top of the stack to the @code{math2ox}.
480: Then, in order to receive the message, we need to call the
481: @code{OxGet[]} function always after executing @code{OxSendMessage[]}.
482: That is @code{OxGet} flushes the communication route to @code{pid}. If
483: we never use the @code{OxSendMessage} function, then we do not need to
484: call the @code{OxGet[]}.
1.5 ohara 485:
486: Fourth, if we send a command expressed in the local language of the OX
487: server, then we need to call the @code{OxExecuteString[]} function.
488:
489: Last, let us close the connection.
490: @example
491: In[7] := OxClose[pid]
492: @end example
1.1 ohara 493:
1.5 ohara 494: @c @node Bibliography,,, Top
495: @c @unnumbered Bibliography
496: @node References,,, Top
497: @unnumbered References
498:
499: @enumerate
500: @item
501: M. Noro, N. Takayama:
502: Design and Implementation of OpenXM, 1996, 1997, 1998, 1999, 2000.
503:
504: @item
505: @code{http://www.math.kobe-u.ac.jp/OpenXM/}
506:
507: @item
508: M. Noro, K. Ohara, N. Takayama:
509: {Introduction to Open Asir}, 1999, Suusiki Shori, Vol 7, No 2,
510: 2--17. (ISBN4-87243-086-7, SEG Publishing, Tokyo). (in Japanese)
511:
512: @item
513: Stephen Wolfram:
514: {The Mathematica Book}, Third edition,
515: Wolfram Media/Cambridge University Press, 1996.
516:
517: @item
518: T. Miyachi:
519: {Mathematica Network Programming},
520: Iwanami Shoten Publishers, 1998. (in Japanese)
521: @end enumerate
1.1 ohara 522:
523: @node Index,,, Top
524: @unnumbered Index
525: @printindex fn
526: @printindex cp
527: @iftex
528: @vfill @eject
529: @end iftex
530: @summarycontents
531: @contents
532: @bye
533:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>