Risa/Asir
*********

Risa および Asir
=============

Risa and Asir
=============

Risa は, 富士通研で開発中の数式処理システム/ライブラリの総称である. Risa の構成は次の通りである.

Risa is the name of whole libraries of a computer algebra system which is under development at FUJITSU LABORATORIES LIMITED. The structure of Risa is as follows.

  * 基本演算部

     The basic algebraic engine

     これは, Risa の内部形式に変換されたオブジェクト (数, 多項式など) の間の演算を実行する部分であり, UNIX の libc.a などと同様の, ライブラリとして存在する. エンジンは, C および アセンブラで記述され, 後述する言語インタフェース Asir の基本演算部として用いられている.

     This is the part which performs basic algebraic operations, such as arithmetic operations, to algebraic objects, e.g., numbers and polynomials, which are already converted into internal forms. It exists, like libc.a of UNIX, as a library of ordinary UNIX system. The algebraic engine is written mainly in C language and partly in assembler. It serves as the basic operation part of Asir, a standard language interface of Risa.

  * メモリ管理部

     Memory Manager

     Risa では, メモリ管理部として, [Boehm,Weiser] によるフリーソフトウェア (gc-5.0alpha2) を用いている. これはガーベジコレクション (以下 GC と呼ぶ) を自動的に行うメモリ割り当て機構を持ち, Risa の各部分はすべてこれにより必要なメモリを得ている.

     Risa employs, as its memory management component (the memory manager), a free software distributed by Boehm (gc-5.0alpha2). It is proposed by [Boehm,Weiser], and developed by Boehm and his colleagues. The memory manager has a memory allocator which automatically reclaims garbages, i.e., allocated but unused memories, and refreshes them for further use. The algebraic engine gets all its necessary memories through the memory manager.

  * Asir

     Asir は, Risa の計算エンジンの言語インタフェースである. Risa では, 比較的容易にユーザ用の言語インタフェースを作ることができる. Asir はその一つの例として作ったもので, C 言語に近い文法をもつ. また, C のデバッガとして広く用いられている dbx 風のデバッガも備えている.

     Asir is a standard language interface of Risa's algebraic engine. It is one of the possible language interfaces, because one can develop one's own language interface easily on Risa system. Asir is an example of such language interfaces. Asir has very similar syntax and semantics as C language. Furthermore, it has a debugger that provide a subset of commands of dbx, a widely used debugger of C language.

Asir の特徴
========

Features of Asir
================

Asir は, 前述の通り, 計算エンジンの言語インタフェースである. 通常 Asir という名前の実行可能ファイルとして提供される. 現在サポートされている機能は概ね次の通りである.

As mentioned in the previous section, Asir is a standard language interface forRisa's algebraic engine. Usually, it is provided as an executable file named asir. Main features supported for the current version of Asir is as follows.

  * C 言語風のユーザ言語

  * 数, 多項式, 有理式の加減乗(除)

  * ベクトル, 行列の演算

  * 最小限のリスト処理

  * 組み込み函数 (因数分解, GCD, グレブナ基底など)

  * ユーザ定義函数によるツール (代数体上の因数分解など)

  * dbx 風のデバッガ

  * 陰函数の描画

  * PARI (see pari) による初等超越函数を含む式の評価

  * UNIX 上での分散計算機能 (Open XM)

  * A C-like programming language

  * Arithmetic operations (addition, subtraction, multiplication and division) on numbers, polynomials and rational expressions

  * Operations on vectors and matrices

  * List processing operations at the minimum

  * Several Built-in functions (factorization, GCD computation, Groebner basis computation etc.)

  * Useful user defined functions(e.g., factorization over algebraic number fields)

  * A dbx-like debugger

  * Plotting of implicit functions

  * Numerical evaluation of mathematical expressions including elementary transcendental functions at arbitrary precision. This feature is in force only if PARI system (see pari).

  * Distributed computation over UNIX

インストレーション
=========

Installation
============

以下の手続きで不明な点, 不都合な点があった場合の問い合わせは

Any questions and any comments on this manual are well come by e-mails to the following address.

     noryo@flab.fujitsu.co.jp

宛に e-mail でお願いします.

UNIX 版
------

UNIX version
------------

必要なファイルは asir.tgz である. これらは全て gzip で圧縮してあるので, 入手後 gzip で展開する. まず, インストールするディレクトリを決める. デフォルトでは /usr/local/lib に asir というディレクトリとしてインストールされることを仮定している. 以下このディレクトリをライブラリディレクトリと呼ぶ.

A file asir.tgz suitable for the taget machine/architecture is required. After getting it, you have to unpack it by gzip. First of all, determine a derectory where binaries and library files are installed. We call the directory the library directory. The following installs the files in /usr/local/lib/asir.

     # gzip -dc asir.tgz | ( cd /usr/local/lib; tar xf - )

個人的に使用する場合には, $HOMEなどに置いてもよい.

In this case you don't have to set any environment variable.

You can install them elsewhere.

     % gzip -dc asir.tgz | ( cd $HOME; tar xf - )

この場合, ライブラリディレクトリの名前を環境変数 ASIR_LIBDIR に設定する必要がある.

In this case you have to set the name of the library directory to the environment variable ASIR_LIBDIR.

     % setenv ASIR_LIBDIR $HOME/asir

Asir 本体は, ライブラリディレクトリの asir である. /usr/local/bin あるいはユーザの実行ファイルサーチパスのどこかにシンボリックリンクを作ると便利である.

Asir itself is in the library directory. It will be convenient to create a symbolic link to it from /usr/local/bin or the user's search path.

     # ln -s /usr/local/lib/asir/asir /usr/local/bin/asir

この状態で asir を起動してみる.

Start asir, and Asir will immediately terminate leaving you a message as follows.

     % /usr/local/bin/asir
     asir_key not found.

     You need a key for each machine on which you want to run Asir.
     In order to get the key, send an e-mail consisting of the following
     single line to risa@sec.flab.fujitsu.co.jp.

     ASIR XXXXXXXX

     After a while, an e-mail will be returned containing only one line like

     YYYYYYYY YYYYYYYY YYYYYYYY

     Create '.../asir_key'
     if necessary and append the returned string to the file.

すると, このようなメッセージが出て asir は終了する. UNIX 版では, マシンごとに key と呼ばれる文字列が必要である. key を入手するためには,

     risa@sec.flab.fujitsu.co.jp

宛に,

     ASIR XXXXXXXX

という 1 行のみからなる e-mail を送ればよい. XXXXXXXX は表示された ID である. 折り返し

     YYYYYYYY YYYYYYYY YYYYYYYY

という形の 1 行のみからなる e-mail が届くので, この 1 行を含む asir_key なるファイルをカレントディレクトリに作って asir を起動してみる.

For UNIX version of Asir, you need a key, a string, for each machine you want to run Asir. In order to get the key, you just need to send an e-mail consisting of a single line like

     ASIR XXXXXXXX

to address

     risa@sec.flab.fujitsu.co.jp

Here, XXXXXXXX is the machine ID notified in the first message from Asir.

After a while, an e-mail will be returned containing only one line like

     YYYYYYYY YYYYYYYY YYYYYYYY

Then, you shall create a new file in the current directory named asir_key containing the returned string in one line.

All after this, call again asir.

     % /usr/local/bin/asir
     This is Risa/Asir, Version 991227.
     Copyright (C) FUJITSU LABORATORIES LIMITED.
     1994-1999. All rights reserved.
     [0]

このようなプロンプトが出れば, 入手した key はそのマシンに対して有効である. key を書いておくファイルに関しては, 環境変数 ASIR_KEY の説明の項で詳しく述べるが, ライブラリディレクトリにここで作成したファイル asir_key を置けば, そのマシン上で全てのユーザが asir を使用できるようになる. asir_key には複数のマシンに対する key を書けるので, ライブラリディレクトリを共有している場合でも asir_key に行を追加していけばよい.

If you get such a prompt ([0]) from Asir, the key you have is valid to the machine you are currently running asir.

When the file asir_key is located on the library directory, all the users of the machine can execute asir. The file asir_key can contain several lines for several key's. This enables users to run several machines sharing the same library directory by simply adding lines for machines to be used. We shall describe about the file for key's in detail in Environment variable.

     # cp asir_key /usr/local/lib/asir

Windows 版
---------

Windows version
---------------

必要なファイルは asirwin.tgz である. 他に, gzip.exe, tar.exe が必要だが, asirwin.tgz と同じディレクトリに用意してある. これら 3 つのファイルを同一ディレクトリにおき, DOS プロンプトから

The necessary file is asirwin.tgz. To unpack it gzip.exe and tar.exe are necessary. They are in the same directory as asirwin.tgz on the ftp server. Putting them in the same directory, execute the following:

     C:\...> tar xzf asirwin.tgz

     C:\...> tar xzf asirwin.tgz

を実行すれば, Asir というディレクトリ (Asir ルートディレクトリ) ができる. 990831 版では, GUI と本体が分離され, またデバッグウィンドウも別プロセスとして GUI が呼び出されるため, Asir ルートディレクトリが正しく登録されていることが必要である.  Asir ルートディレクトリのサブディレクトリ bin に asirgui.exe (GUI), engine.exe (本体) が置かれている. asirgui.exe の初回の立ち上げは, エクスプローラから行う. これにより

Then a directory Asir (Asir root directory) is created, which has subdirectories named bin and lib. To set up it, invoke bin\asirgui.exe from Explorer and click OK.  Then the name of Asir root directory is set to the following registries.

     HKEY_LOCAL_MACHINE\SOFTWARE\FUJITSU\Asir\99.03.31\Directory

     HKEY_LOCAL_MACHINE\SOFTWARE\FUJITSU\Asir\99.03.31\Directory

というレジストリに Asir ルートディレクトリが正しく登録される.

コマンドラインオプション
============

Command line options
====================

コマンドラインオプションは次の通り.

Command-line options for the command asir are as follows.

-heap NUMBER

     Risa/Asir では, 4KB のブロックをメモリ割り当ての単位として用いている. デフォルトでは, 初期 heap として, 16 ブロック (64KB) 割り当てるが, それを変更する場合, -heap を用いる. 単位はブロックである. heap の大きさは, heap() 函数で調べることができる (単位はバイト).

     In Risa/Asir, 4KB is used as an unit, called block, for memory allocation. By default, 16 blocks (64KB) are allocated initially. This value can be changed by giving an option -heap a number parameter in unit block. Size of the heap area is obtained by a Built-in function heap(), the result of which is a number in Bytes.

-adj NUMBER

     この値が大きいほど, 使用メモリ量は大きくなるが, GC 時間が少なくなる. NUMBER として 1 以上の整数が指定できる. デフォルトでは 3 である. この値が 1 以下になると GC をしない設定になるので要注意である. heap をなるべく伸ばさずに, GC を主体にしてメモリ管理したい場合には, この値を大きく (例えば 8) 設定する.

     Heap area will be stretched by the memory manager, if the size of reclaimed memories is less than 1/NUMBER of currently allocated heap area. The default value for NUMBER is 3. If you do not prefer to stretch heap area by some reason, perhaps by restriction of available memories, but if prefer to resort to reclaiming garbages as far as possible, then a large value should be chosen for NUMBER, e.g., 8.

-norc
     初期化ファイル $HOME/.asirrc を読まない.

     When this option is specified, Asir does not read the initial file $HOME/.asirrc.

-f FILE

     標準入力の代わりに, FILE から入力を読み込んで実行する. エラーの際にはただちに終了する.

     Instead of the standard input, FILE is used as the input. Upon an error, the execution immediately terminates.

-paristack NUMBER

     PARI (see pari) 専用の領域の大きさを指定する. 単位はバイト. デフォルトでは 1 MB.

     This option specifies the private memory size for PARI (see pari). The unit is Bytes. By default, it is set to 1 MB.

-maxheap NUMBER

     heap 領域の上限を指定する. 単位はバイト. デフォルトでは無制限. UNIX の場合, 実際には limit コマンドで表示される datasize の値に制限されているため, -maxheap の指定がなくても一定量以上に heap を獲得できない場合があるので注意.)

     This option sets an upper limit of the heap size. The unit is Bytes. Note that the size is already limited by the value of datasize displayed by the command limit on UNIX.

環境変数
====

Environment variable
====================

Asir の実行に関するいくつかの環境変数が存在する. UNIX 上では環境変数は shell のコマンドラインから直接設定するか, shell の rc ファイルで設定する. Windows NT では, [設定]->[システム]->[環境] で設定する. Windows 95/98 では, c:\autoexec.bat に書いて reboot する.

There exist several environment variables concerning with an execution of Asir. On UNIX, an environment variable is set from shells, or in rc files of shells. On Windows NT, it can be set from [Control Panel] ->[Environment]. On Windows 95/98, it can be set in c:\autoexec.bat. Note that the setting takes effect after rebooting the machine on Windows 95/98.

  * ASIR_KEY

     UNIX 版では, Asir が起動されたマシンに対する key がなければそのマシン上で Asir は動作しない. key は 16 進 8 桁 3 ワードからなり,

     Asir shall not work unless a key for the machine on which Asir is invoked is given. The key consists of a string which denotes 3 word hexadecimal number, each of which has 8 hexadecimal digits. In order to run Asir for several machines, several key's can be written together on a same file as follows.

          % cat asir_key
          cf6f236c 61a35091 dddc4529 geisha
          82281685 d1929945 a8bd24ca yorktown
          34b75d30 63f8df93 3e881113 nyanchu

     という形で複数台のマシンに対する key を一つのファイルにまとめて書くことができる. key の後ろは無視されるので, コメントを書くことができる. key を含むファイルは, 以下の順でサーチされる.

     The text after each key is neglected to the end-of-line. This is convenient to comment on the respective key. Files containing key's are searched by the following order.

      1. 環境変数 ASIR_KEY に指定されたファイル

          File set to environment ASIR_KEY

      2. カレントディレクトリの asir_key

          File asir_key on the current directory.

      3. 環境変数 ASIR_LIBDIR で指定されたディレクトリ (指定がなければ /usr/local/lib/asir) の asir_key

          Files on the directory specified by environment ASIR_LIBDIR. (File asir_key on /usr/local/lib/asir/, if environment ASIR_LIBDIR is not set.)

  * ASIR_LIBDIR

     Asir のライブラリディレクトリ, すなわちユーザ言語で書かれたファイルなどがおかれるディレクトリ. 指定がない場合 UNIX 版では /usr/local/lib/asir, Windows 版では Asir メインディレクトリの下の lib ディレクトリが用いられる.

     The library directory of Asir, i.e., the directory where , for example, files containing programs written in Asir. If not specified, on UNIX, /usr/local/lib/asir is used by default. On Windows, lib in Asir root directory is used by default. This environment will be useful in a case where Asir binaries are installed on a private directory of the user.

  * ASIRLOADPATH

     ロードされるファイルがあるディレクトリを UNIX の場合 ':', Windowsの場合 ';' で区切って並べる. ディレクトリは左から順にサーチされる. この指定がない場合, および指定されたファイルが ASIRLOADPATH になかった場合, ライブラリディレクトリもサーチされる.

     This environment specifies directories which contains files to be loaded by Asir command load(). Directories are separated by a `:' on UNIX, a ';' on Windows respectively. The search order is from the left to the right. After searching out all directories in ASIRLOADPATH, or in case of no specification at all, the library directory will be searched.

  * HOME

     -NORC オプションつきで起動しない場合, $HOME/.asirrcがあれば, 予めこのファイルを実行する. HOME が設定されていない場合, UNIX 版ではなにも読まないが, Windows 版では Asir メインディレクトリ (get_rootdir() で返されるディレクトリ) の .asirrc を探し, あればそれを実行する.

     If Asir is invoked without -NORC, $HOME/.asirrc, if exists, is executed. If HOME is not set, nothing is done on UNIX. On Windows, .asirrc in Asir root directory is executed if it exists.

起動から終了まで
========

Starting and Terminating an Asir session
========================================

Asir を起動すると,

Run Asir, then the copyright notice and the first prompt will appear on your screen, and a new Asir session will be started.

     [0]

なるプロンプトが表示され, セッションが開始する. $HOME/.asirrc (Windows 版の場合, HOME 設定されていない場合には get_rootdir() で返されるディレクトリにある .asirrc) が存在している場合, このファイルを Asir ユーザ言語でかかれたファイルと見なし, 解釈実行する.

When initialization file $HOME/.asirrc exists, Asir interpreter executes it at first taking it as a program file written in Asir.

プロンプトは入力の番号を表す. セッションは, end; または quit; を入力することにより終了する. 入力は, ; または $ までを一区切りとして評価される. ; のとき結果は表示され, $ のとき表示されない.

The prompt indicates the sequential number of your input commands to Asir. The session will terminate when you input end; or quit; to Asir. Input commands are evaluated statement by statement. A statement normally ends with its terminator ; or $. (There are some exceptions. See, syntax of Asir.) The result will be displayed when the command, i.e. statement, is terminated by a ;, and will not when terminated by a $.

     % asir
     [0] A;
     0
     [1] A=(x+y)^5;
     x^5+5*y*x^4+10*y^2*x^3+10*y^3*x^2+5*y^4*x+y^5
     [2] A;
     x^5+5*y*x^4+10*y^2*x^3+10*y^3*x^2+5*y^4*x+y^5
     [3] a=(x+y)^5;
     evalpv : invalid assignment
     return to toplevel
     [3] a;
     a
     [4] fctr(A);
     [[1,1],[x+y,5]]
     [5] quit;
     %

この例では, A, a, x, y なる文字が使用されている. A はプログラムにおける変数で, a, x, y は数学的な意味での不定元である. 一般にプログラム変数は大文字で始まり, 不定元は小文字で始まる. この例でわかるように, プログラム変数は, 数, 式などを格納しておくためのものであり, C 言語などにおける変数に対応する. 一方, 不定元はそれ自身で値を持つことはできず, 従って, 不定元に対する代入は許されない. 後に示すが, 不定元に対する代入は, 組み込み函数 subst() により明示的に行われる.

In the above example, names A, a, x and y are used to identify mathematical and programming objects. There, the name A denotes a program variable (some times called simply as a program variable.) while the other names, a, x and y, denote mathematical objects, that is, indeterminates. In general, program variables have names which begin with capital letters, while names of indeterminates begin with small letters. As you can see in the example, program variables are used to hold and keep objects, such as numbers and expressions, as their values, just like variables in C programming language. Whereas, indeterminates cannot have values so that assignment to indeterminates are illegal. If one wants to get a result by substituting a value for an indeterminate in an expression, it is achieved by the function subst as the value of the function.

割り込み
====

Interruption
============

計算を実行中に割り込みをかけたい場合, 割り込みキャラクタ(通常は C-c, DOS 版では C-x, Mac 版では command+. ) を入力する.

To interrupt the Asir execution, input an interrupt character from the keyboard.  A C-c is usually used for it. (Notice: C-x for DOS version; command+. for Macintosh version.)

     @ (x+y)^1000;
     C-cinterrupt ?(q/t/c/d/u/w/?)

各選択肢の意味は次の通り.

Here, the meaning of options are as follows.

q
     Asir を終了する. (確認あり)

t
     トップレベルに戻る. (確認あり)

c
     実行を継続する.

d
     デバッグモードに入る. デバッガに関しては see デバッガ.

u
     register_handler() (see ox_reset ox_intr register_handler) で登録された関数を実行後トップレベルに戻る. (確認あり)

w
     中断点までの函数の呼び出し列を表示する.

?
     各選択肢の意味を説明する.

q
     Terminates Asir session. (Confirmation requested.)

t
     Returns to toplevel. (Confirmation requested.)

c
     Resumes to continue the execution.

d
     Enters debugging mode at the next statement of the Asir program, if Asir has been executing a program loaded from a file. Note that it will sometimes take a long time before entering debugging mode when Asir is executing basic functions in the algebraic engine, (e.g., arithmetic operation, factorization etc.) Detailed description about the debugger will be given in Debugger.

u
     After executing a function registered by register_handler() (see ox_reset ox_intr register_handler), returns to toplevel. A confirmation is prompted.

w
     Displays the calling sequence up to the interruption.

?
     Show a brief description of options.

エラー処理
=====

Error handling
==============

組み込み函数に不正な型の引数を渡した場合などには実行が中断されるが, ユーザ函数の中でエラーが起きた場合にはトップレベルに戻る前に自動的にデバッグモードに入る. この状態でエラーの場所, 直前の引数の値などを調べることができる. 表示されるエラーメッセージはさまざまであり, 内部の函数名に引き続いてメッセージが表示される. これは, 呼び出された組み込み函数と必ずしも対応はしない.

When arguments with illegal types are given to a built-in function, an error will be detected and the execution will be quit. In many cases, when an error is detected in a built-in function, Asir automatically enters debugging mode before coming back to toplevel. At that time, one can examine the state of the program, for example, inspect argument values just before the error occurred. Messages reported there are various depending on cases.  They are reported after the internal function name.  The internal function name sometimes differs from the built-in function name that is specified by the user program.

その他, さまざまな原因により内部演算函数においてエラーが生ずることがある. UNIX 版の場合, これは次のいずれかの internal error として報告され, 通常のエラーと同様に扱って, デバッグモードに入る.

In the execution of internal functions, errors may happen by various reasons.  The UNIX version of Asir will report those errors as one of the following internal error's, and enters debugging mode just like normal errors.

SEGV
BUS ERROR

     組み込み函数によっては, 引数の型を厳密にチェックせずに演算ルーチンに引き渡してしまうものも存在している. このような状況において, 不正なポインタ, あるいは NULL ポインタによるアクセス違反があった場合, これらのエラーとなる.

     Some of the built-in functions transmit their arguments to internal operation routines without strict type-checking.  In such cases, one of these two errors will be reported when an access violation caused by an illegal pointer or a NULL pointer is detected.

BROKEN PIPE

     プロセス間通信において, 相手先のプロセスとの間のストリームが既に存在していない場合 (例えば既に相手先のプロセスが終了している場合など) に, そのストリームに入出力しようとした場合にこのエラーとなる.

     In the process communication, this error will be reported if a process attempts to read from or to write onto the partner process when the stream to the partner process does not already exist, (e.g., terminated process.)

これらは実際には, 組み込み函数の入口において, 引数を完全にチェックすることにより大部分は防げるが, 手間が多くかかることと, 場合によっては効率を落すことにもなるため, あえて引数チェックはユーザ任せにしてある.

For UNIX version, even in such a case, the process itself does not terminate because such an error can be caught by signal() and recovered. To remove this weak point, complete type checking of all arguments are indispensable at the entry of a built-in function, which requires an enormous amount of re-making efforts.

計算結果, 特殊な数
==========

Referencing results and special numbers
=======================================

@ はエスケープ文字として使用される. 現在次のような規定がある.

An @ used for an escape character; rules currently in force are as follows.

@N
     N 番目の計算結果.

@@
     直前の計算結果.

@i
     虚数単位.

@pi
     円周率.

@e
     自然対数の底.

@
     2 元体 GF(2) 上の一変数多項式の変数 (不定元).

@>, @<, @>=, @<=, @==, @&&, @||
     quantifier elimination における, 一階述語論理演算子

@N
     The evaluated result of N-th input command

@@
     The evaluated result of the last command

@i
     The unit of imaginary number, square root of -1.

@pi
     The number pi, the ratio of a circumference of the circle and its diameter.

@e
     Napier's number, the base of natural logarithm.

@
     A generator of GF(2^m), a finite field of characteristic 2, over GF(2). It is a root of an irreducible univariate polynomial over GF(2) which is set as the defining polynomial of GF(2^m).

@>, @<, @>=, @<=, @==, @&&, @||
     Fist order logical operators. They are used in quantifier elimination.

     [0] fctr(x^10-1);
     [[1,1],[x-1,1],[x+1,1],[x^4+x^3+x^2+x+1,1],[x^4-x^3+x^2-x+1,1]]
     [1] @@[3];
     [x^4+x^3+x^2+x+1,1]
     [2] eval(sin(@pi/2));
     1.000000000000000000000000000000000000000000000000000000000
     [3] eval(log(@e),20);
     0.99999999999999999999999999998
     [4] @0[4][0];
     x^4-x^3+x^2-x+1
     [5] (1+@i)^5;
     (-4-4*@i)
     [6] eval(exp(@pi*@i));
     -1.0000000000000000000000000000
     [7] (@+1)^9;
     (@^9+@^8+@+1)

トップレベルで計算された値はこのようにヒストリとして取り出し可能であるが, このことは, ガベージコレクタにとっては負担をもたらす可能性がある. 特に, 大きな式をトップレベルで計算した場合, その後の GC 時間が急速に増大する可能性がある. このような場合, delete_history() (see delete_history) が有効である.

As you can see in the above example, results of toplevel computation can be referred to by @ convention. This is convenient for users, while it sometimes imposes a heavy burden to the garbage collector. It may happen that GC time will rapidly increase after computing a very large expression at the toplevel. In such cases delete_history() (see delete_history) takes effect.