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