Distributed Maple 1.1.17 ------------------------ Copyright (C) 1998-2004 Wolfgang Schreiner (RISC-Linz), see file COPYRIGHT See http://www.risc.uni-linz.ac.at/software/distmaple Incompatibilities to Previous Versions -------------------------------------- Starting with version 1.1.0, the semantics of the last two fields of a "dist.systems" entry have slightly changed. If you do not know better, set the first field to 1, the second to 0. General ------- This package consists of two parts: 1) A Java class library located in subdirectory 'dist' which implements a general purpose communication framework and scheduling mechanism for distributed applications; the main program is represented by the class 'dist.Scheduler'. 2) A binding which allows to access the Java scheduler from the computer algebra system 'Maple' via the interface contained in 'dist.maple' (a sequential implementation of this interface that does not need the Java scheduler is contained in 'seq.maple'). Requirements ------------ The frontend runs on a Unix machine with Maple 6, Maple V.5 or Maple V.4. The clients run on Unix or Windows 95/NT machines with Maple 6, Maple V.5 or Maple V.4; in case of a Windows client, the machine must run a connection server (see the description in the manual). Frontend and all clients must all run the same version of Maple. Installation ------------ See File INSTALL for more details. To use the application framework for implementing distributed Maple computations, follow these steps: 1) Install the directory 'dist' in some place (or places) such that it can be read from any machine that participates in the computation. 2) Copy 'dist.systems' into the directory from where the computation is started and edit it appropriately such that the scheduler knows how to startup the distributed session. In particular, a) You must be able to invoke a process by a 'rsh' (remote shell)-style program on each remote machine (alternatively, on a remote machine a server may be running that accepts connection requests and invokes the process locally, see the documentation). b) A Java virtual machine (e.g. a 'java' interpreter) must be installed on the local *and* on each remote machine and must have access to the 'dist' library. c) Maple must be installed on the local *and* on each remote machine and must be able to read 'dist.maple' (i.e., 'dist.maple6' for Maple 6, 'dist.maple5' for Maple V.5, 'dist.maple4' for Maple V.4). The corresponding commands must be defined in 'dist.systems' for each class of remote machine that shall participate in the computation (each class labeled by some key string). 3) It might (but should not) be necessary to edit a few of the commands defined in 'dist.maple' that are invoked on the local host system. The current setup should work on most Unix machines, i.e., only edit the file if something goes wrong in the initialization phase (see below). Java on Linux ------------- Java's "green threads" on Linux gives sometimes massive problems with message throughput (messages are delayed for a very long time). If possible, use a Java version that supports "native threads" ("java -native"), e.g. JDK 2. The JDK 1.1.x "java" script for Linux has a problem that lets Maple processes created by System.exec() crash. Please edit the script by commenting the lines # LD_PRELOAD=/lib/libBrokenLocale.so.1 # export LD_PRELOAD (which solves the problem on my system). Java on SGI Origin ------------------ Java's "native threads" on an SGI Origin with more than 8 processors or so gives sometimes massive problems with message throughput (messages are delayed for a very long time). Use "java -green". Usage ----- If the Java subdirectory 'dist' ist not located in your current subdirectory (e.g. by a symbolic link to the actual installation directory), then you have to set the environment variable CLASSPATH to include the directory where this subdirectory is located, e.g. CLASSPATH=/usr/local/lib/jdk:/home/info/www/software/distmaple Start 'maple' (or 'xmaple') and load the binding file by typing e.g. > read `dist.maple`; You may then startup the distributed environment by typing > dist[initialize]([[machine, key],...]); listing each 'machine' (symbolic name or IP-address) and its 'key' (used in 'dist.systems' to denote a class of machines). This should result in one line of output for each machine: Connecting machine... By the way, you may also use an empty list of machines; in this case only the current Maple process is used for running the computations. Now you may start tasks and wait for their results, i.e., run a distributed computation, e.g. > t1 := dist[start](int, x^n, x): > t2 := dist[start](int, x^n, n): > dist[wait](t1) + dist[wait](t2); Finally you should type > dist[terminate](); to shutdown the environment. Online Visualization -------------------- You may call > dist[visualize](600, 300, 2, 120); to create a window of size 600x300 which displays the usage of each machine employed in the computation during the last 120 seconds with updates every 2 seconds. Calling this command several times with varying parameters gives you different windows with different execution snapshots. Windows may be individually resized and closed. Post-Execution Visualization ---------------------------- Before calling "dist[initialize]", you may also say > dist[trace](file); by which some kind of trace information is generated in the denoted file. After system termination, you may call on the command line e.g. % java visual.Main file initialize terminate 100 100 This generates some files "file-*.fig" each of which contains a diagram of size 100x100 mm that visualizes some aspect of the program's runtime behavior. The files are in the Fig 3.2 format; you may use, e.g., "xfig" to browse them and generate images in various formats. The predefined tags "initialize" and "terminate" used above denote the range of the visualization. By calling > dist[label](key); during program execution, you may generate such a label "key" on your own. Documentation ------------- For more information, see the documentation located on the Web page http://www.risc.uni-linz.ac.at/software/distmaple respectively contained in the distribution report.ps (PostScript File) html/index.html (HTML pages) Bugs and Extensions ------------------- Please report problems and bugs to me, i.e., Wolfgang Schreiner http://www.risc.uni-linz.ac.at/people/schreine Please be so kind to cite the use of this software in any resulting application or publication. It should be fairly straight-forward to use the Java framework for connecting other systems as well by defining corresponding language bindings. Support for heterogeneous distributed applications combining different kinds of systems is in principle possible but requires some modifications in the current protocol of the scheduler. $Id: README,v 1.39 2006/01/16 11:29:25 schreine Exp schreine $