その他
===

Miscellaneouses
===============

ctrl
----

ctrl("SWITCH"[,OBJ])
     :: 環境設定

     :: Sets the value of SWITCH.

return
     設定されている値

     value of SWITCH

switch
     スイッチ名

     switch name

obj
     パラメタ

     parameter

  * Asir の実行環境の設定変更, 参照を行う.

  * SWITCH のみの場合, そのスイッチの現在の状態を返す.

  * OBJ が与えられているとき, その値を設定する.

  * スイッチは文字列として入力する. すなわちダブルクォートで囲む.

  * スイッチは次の通り. 以下で, on は 1, off は 0 を意味する.

     cputime
          on の時 CPU time および GC time を表示, off の時 表示しない. cputime() を参照. ctrl("cputime",ONOFF) は cputime(ONOFF) と同じである.

     nez
          EZGCD のアルゴリズムの切替え. デフォルトで 1 であり, とくに切替える必要はない.

     echo
          on の時は標準入力を繰り返して出力し, off の時は標準入力を繰り返さない. output コマンドを用いる際に有効である.

     bigfloat
          on の時, 入力された浮動小数は bigfloat に変換され, 浮動小数演算は PARI (see pari) により行われる. デフォルトの有効桁数は 9 桁である. 有効桁数を増やしたい時には setprec() を用いる. off の時, 入力された浮動小数は, 倍精度浮動小数に変換される.

     adj
          ガーベッジコレクションの頻度の変更. 1 以上の有理数が指定できる. デフォルト値は 3. 1 に近い程, ガーベッジコレクションせずにヒープを大きくとるようになる. 整数値はコマンドラインで指定できる. See コマンドラインオプション.

     verbose
          on の時, 函数の再定義時にメッセージを表示する.

     hex
          1 のとき, 整数は 0x で始まる 16 進数として表示される. -1 のとき, 16 進数は, 間に | をはさんで 8 桁ごとに区切って表示される.

     ox_batch
          1 のとき, 送信バッファがいっぱいになった時のみ自動的に flush. 0 のとき, データ, コマンド送信毎に flush. (デフォルト値は 0.) See 分散計算

     ox_check
          1 のとき, 送信データを相手プロセスが受け取れるかどうかチェックする. 0 のときしない. (デフォルト値は 1.) See 分散計算

  * This function is used to set or to get the values of switches. The switches are used to control an execution of Asir.

  * If OBJ is not specified, the value of SWITCH is returned.

  * If OBJ is specified, the value of SWITCH is set to OBJ.

  * Switches are specified by strings, namely, enclosed by two double quotes.

  * Here are of switches of Asir.

     cputime
          If `on', CPU time and GC time is displayed at every top level evaluation of Asir command; if `off', not displayed. See cputime tstart tstop. (The switch is also set by command cputime(1), and reset by cputime(0).)

     nez
          Selection for EZGCD algorithm.  It is set to 1 by default.  Ordinary users need not change this setting.

     echo
          If `on', inputs from the standard input will be echoed onto the standard output.  When executing to load a file, the contents of the file will be written onto the standard output. If `off', the inputs will not be echoed. This command will be useful when used with command output.

     bigfloat
          If `on', floating operations will be done by PARI system with arbitrary precision floating point operations. Default precision is set to 9 digits.  To change the precision, use command setprec. If `off', floating operations will be done by Asir's own floating operation routines with a fixed precision operations of standard floating double.

     adj
          Sets the frequency of garbage collection. A rational number greater than or equal to 1 can be specified. The default value is 3. If a value closer to 1 is specified, larger heap is allocated and as a result, the frequency of garbage collection decreases. See Command line options.

     verbose
          If `on' a warning messages is displayed when a function is redefined.

     hex
          If 1 is set, integers are displayed as hexadecimal numbers with prefix 0x. if -1 is set, hexadecimal numbers are desplayed with | inserted at every 8 hexadecimal digits.

     ox_batch
          If 'on', the OpenXM send buffer is flushed only when the buffer is full. If 'off', the buffer is always flushed at each sending of data or command. The default value is 'off'. See Distributed computation

     ox_check
          If 'on' the check by mathcap is done before sending data. The default value is 'on'. See Distributed computation

参照

References
     cputime tstart tstop, output, pari, setprec, eval.

debug
-----

debug
     :: デバッグモードに入る.

     :: Forces to enter into debugging mode.

  * debug は無引数の函数であるが, () なしで呼び出せる.

  * デバッグモードに入るとプロンプトが (debug) となり, コマンド受け付け状態となる. quit を入力するとデバッガから抜ける.

  * デバッグモードについての詳細は see デバッガ.

     Function debug is a function with no argument. It can be called without ().

  * In the debug-mode, you are prompted by (debug) and the debugger is ready for commands. Typing in quit (Note! without a semicolon.) brings you to exit the debug-mode.

  * See Debugger for details.

     [1] debug;
     (debug) quit
     0
     [2]

error
-----

error(MESSAGE)
     :: プログラム中で強制的にエラーを発生させる.

     :: Forces Asir to cause an error and enter debugging mode.

message
     文字列

     string

  * 一般に, 引数の間違いなど, 続行不可能なエラーが組み込み函数において発生した時, トップレベルに戻る前に, 可能ならばそのエラーの時点でデバッグモードに入る. error() は, ユーザ函数の内部でこの動作と同様の動作を行わせるための函数である.

  * 引数は, error() が呼び出される際に表示されるメッセージで, 文字列である.

  * ユーザ函数において, 変数をチェックして, あり得ない値の場合に error() を呼び出すようにしておけば, その時点で自動的にデバッグモードに入れる.

  * When Asir encounters a serious error such that it finds difficult to continue execution, it, in general, tries to enter debugging mode before it returns to top level. The command error() forces a similar behavior in a user program.

  * The argument is a string which will be displayed when error() will be executed.

  * You can enter the debug-mode when your program encounters an illegal value for a program variable, if you have written the program so as to call error() upon finding such an error in your program text.

     % cat mod3
     def mod3(A) {
             if ( type(A) >= 2 )
                     error("invalid argument");
             else
                     return A % 3;
     }
     end$
     % asir
     [0] load("mod3");
     1
     [3] mod3(5);
     2
     [4] mod3(x);
     invalid argument
     stopped in mod3 at line 3 in file "./mod3"
     3                       error("invalid argument");
     (debug) print A
     A = x
     (debug) quit
     return to toplevel
     [4]

参照

References
     debug.

help
----

help(["FUNCTION"])
     :: 函数の説明を表示する.

     :: Displays the description of function FUNCTION.

return
     0

function
     函数名

     function name

  * 無引数の時, 最小限の説明が表示される. 函数名が引数として与えられたとき, 標準ライブラリディレクトリにある help というディレクトリに同名のファイルがあれば, 環境変数 PAGER に設定されているコマンド, あるいは more を呼び出してそのファイルを表示する.

  * Windows 版では, コマンドラインからのヘルプ呼び出しは未サポートだが, メニューから HTML 形式のものを呼び出し用いることができる.

  * If invoked without argument, it displays rough usage of Asir.

  * If a function name is given and if there exists a file with the same name in the directory help under standard library directory, the file is displayed by a command set to the environmental variable PAGER or else command more.

  * On Windows HTML-style help is available from the menu.

time
----

time()
     :: セッション開始から現在までの CPU 時間および GC 時間を表示する

     :: Returns a four element list consisting of total CPU time, GC time, the elapsed time and also total memory quantities requested from the start of current Asir session.

return
     リスト

     list

  * CPU 時間および GC 時間の表示に関するコマンドである.

  * GC 時間とは, ガーベジコレクタにより消費されたと見なされる時間, CPU 時間は, 全体の CPU 時間から GC 時間を引いた残りで, 単位は秒である.

  * time() は引数なしで, セッション開始から現在までの CPU 時間, GC 時間, 現在までに要求されたメモリののべ容量, およびセッション開始から現在までの経過時間の表示をする. すなわち, [CPU 時間 (秒), GC 時間 (秒), メモリ量 (ワード), 経過時間 (秒)] なるリストを返す. 1 ワードは通常 4 バイトである.

  * 計算の実行開始時, 終了時の time() から, その計算に対する CPU 時間, GC 時間がわかる.

  * メモリ量は多倍長数ではないため, ある値を越えると無意味な値となるためあくまでも目安として用いるべきである.

  * ctrl() や cputime() により cputime スイッチが on になっている場合には, トップレベルの文を一つの単位として, その実行時間が表示される. しかし, プログラムの内部などで, 特定の計算に対する計算時間を知りたい時には, time() などを使う必要がある.

  * getrusage() が使える UNIX 上では time() は信頼性のある値を返すが, Windows 95, 98 上では時刻を用いるほか方法がないため経過時間そのものが表示される. よって, 待ち状態があると, それも経過時間に加算される.

  * These are commands regarding CPU time and GC time.

  * The GC time is the time regarded to spent by the garbage collector, and the CPU time is the time defined by subtracting the GC time from the total time consumed by command Asir.  Their unit is `second.'

  * Command time() returns total CPU time and GC time measured from the start of current Asir session. It also returns the elapsed time. Time unit is `second.' Moreover, it returns total memory quantities in words (usually 4 bytes) which are requested to the memory manager from the beginning of the current session. The return value is a list and the format is [CPU time, GC time, Memory, Elapsed time].

  * You can find the CPU time and GC time for some computation by taking the difference of the figure reported by time() at the beginning and the ending of the computation.

  * Since arbitrary precision integers are NOT used for counting the total amount of memory request, the number will eventually happen to become meaningless due to integer overflow.

  * When cputime switch is active by ctrl() or by cputime(), the execution time will be displayed after every evaluation of top level statement. In a program, however, in order to know the execution time for a sequence of computations, you have to use time() command, for an example.

  * On UNIX, if getrusage() is available, time() reports reliable figures. On Windows NT it also gives reliable CPU time. However, on Windows 95/98, the reported time is nothing but the elapsed time of the real world. Therefore, the time elapsed in the debug-mode and the time of waiting for a reply to interruption prompting are added to the elapsed time.

     [72] T0=time();
     [2.390885,0.484358,46560,9.157768]
     [73] G=hgr(katsura(4),[u4,u3,u2,u1,u0],2)$
     [74] T1=time();
     [8.968048,7.705907,1514833,63.359717]
     [75] ["CPU",T1[0]-T0[0],"GC",T1[1]-T0[1]];
     [CPU,6.577163,GC,7.221549]

参照

References
     cputime tstart tstop.

cputime, tstart, tstop
----------------------

cputime(ONOFF)
     :: 引数が 0 ならば cputime の表示を止める. それ以外ならば表示を行う.

     :: Stop displaying cputime if its argument is 0, otherwise start displaying cputime after every top level evaluation of Asir command.

tstart()
     :: CPU time 計測開始.

     :: Resets and starts timer for CPU time and GC time.

tstop()
     :: CPU time 計測終了および表示.

     :: Stops timer and then displays CPU time GC time elapsed from the last time when timer was started.

return
     0

onoff
     フラグ (任意)

     flag (arbitrary)

  * cputime() は, 引数が 0 ならば CPU time の表示を止める. それ以外ならば表示を行う.

  * tsart は引数なし, () なしで, CPU time 計測を開始する.

  * tstop は引数なし, () なしで, CPU time 計測を終了, および表示する.

  * cputime(ONOFF) は ctrl("cputime",ONOFF) と同じである.

  * tstart, tstop は, 入れ子にして使われることは想定していないため, そのような可能性がある場合には, time() による計測を行う必要がある.

  * cputime() による on, off は, 単に表示の on, off であり, トップレベルの一つの文に対する計測は常に行われている. よって, 計算を始めてからでも, 計算終了前にデバッガに入って cputime(1) を実行させれば計算時間は表示される.

  * Command cputime() with NON-ZERO argument enables Asir to display CPU time and GC time after every evaluation of top level Asir command. The command with argument 0 disables displaying them.

  * Command tstart() starts measuring CPU time and GC time without arguments.  The parentheses () may be omitted.

  * Command tstop() stops measuring CPU time and GC time and displays them without arguments. The parentheses () may be omitted.

  * Command cputime(ONOFF) has same meaning as ctrl("cputime",ONOFF).

  * Nested use of tstart() and tstop() is not expected. If such an effect is desired, use time().

  * On and off states by cputime() have effects only to displaying mode.  Time for evaluation of every top level statement is always measured. Therefore, even after a computation has already started, you can let Asir display the timings, whenever you enter the debug-mode and execute cputime(1).

     [49] tstart$
     [50] fctr(x^10-y^10);
     [[1,1],[x+y,1],[x^4-y*x^3+y^2*x^2-y^3*x+y^4,1],[x-y,1],
     [x^4+y*x^3+y^2*x^2+y^3*x+y^4,1]]
     [51] tstop$
     80msec + gc : 40msec

参照

References
     time, ctrl.

heap
----

heap()
     :: 現在のヒープの大きさを返す. (単位:バイト)

     :: Heap area size currently in use.

return
     自然数

     non-negative integer

  * 現在のヒープの大きさ(単位 : バイト) を返す. ヒープとは, Asir のさまざまな数式や, ユーザプログラムなどがおかれるメモリの領域で, ガーベジコレクタにより管理されている. プログラムの動作中は, ヒープの大きさは単調非減少であり, 実メモリの量をこえて大きくなった場合には, OS によるスワップエリアへの読み書きがほとんどの計算時間を占めることになる.

  * 実メモリが少ない場合には, 起動時の -adj オプションにより, GC 主体の設定を行っておく必要がある.

  * Command heap() returns an integer which is the byte size of current Asir heap area.

     Heap is a memory area where various data for expressions and user programs of Asir and is managed by the garbage collector. While Asir is running, size of the heap is monotonously non-decreasing against the time elapsed.  If it happens to exceed the real memory size, most (real world) time is consumed for swapping between real memory and disk memory.

  * For a platform with little real memory, it is recommended to set up Asir configuration tuned for GC functions by -adj option at the activation of Asir. (see Command line options.)

     % asir -adj 16
     [0] load("fctrdata")$
     0
     [97] cputime(1)$
     0msec
     [98] heap();
     524288
     0msec
     [99] fctr(Wang[8])$
     3.190sec + gc : 3.420sec
     [100] heap();
     1118208
     0msec
     [101] quit;
     % asir
     [0] load("fctrdata")$
     0
     [97] cputime(1)$
     0msec
     [98] heap();
     827392
     0msec
     [99] fctr(Wang[8])$
     3.000sec + gc : 1.180sec
     [100] heap();
     1626112
     0msec
     [101] quit;

参照

References

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

     Command line options.

version
-------

version()
     :: Asir のバージョンを返す.

     :: Version identification number of  Asir.

return
     自然数

     integer

  * Asir のバージョンを自然数で返す.

     Command version() returns the version identification number , an integer of Asir in use.

     [0] version();
     991214

shell
-----

shell(COMMAND)
     :: COMMAND をシェルコマンドとして実行する.

     :: Execute shell commands described by a string COMMAND.

return
     自然数

     integer

command
     文字列

     string

  * COMMAND を C の system() 函数によりシェルコマンドとして実行する. シェルの終了ステータスを返す.

     Execute shell commands described by a string COMMAND by a C function system().  This returns the exit status of shell as its return value.

     [0] shell("ls");
     alg             da              katsura         ralg            suit
     algt            defs.h          kimura          ratint          test
     alpi            edet            kimura3         robot           texput.log
     asir.o          fee             mfee            sasa            wang
     asir_symtab     gr              mksym           shira           wang_data
     base            gr.h            mp              snf1            wt
     bgk             help            msubst          solve
     chou            hom             p               sp
     const           ifplot          proot           strum
     cyclic          is              r               sugar
     0
     [1]

map
---

map(FUNCTION,ARG0,ARG1,...)
     :: リスト, 配列の各要素に函数を適用する.

     :: Applies a function to each member of a list or an array.

return
     ARG0 と同じ型のオブジェクト

     an object of the same type as ARG0.

function
     函数名

     the name of a function

arg0
     リスト, ベクトル, 行列

     list, vector or matrix

arg1, ...
     任意 (残りの引数)

     arbitrary (the rest of arguments)

  * ARG0 の各要素を最初の引数, ARG1 以下の残りの引数として函数 FUNCTION を呼び出し, ARG0 の対応する要素の位置に函数呼び出しの結果が入った同じ型のオブジェクトを生成して返す.

  * FUNCTION は, ダブルクォートのない函数名を用いる.

  * FUNCTION にプログラム変数は使えない.

  * ARG0 がリスト, ベクトル, 行列以外の場合, 単に ARG0, ARG1, ... を引数として FUNCTION を呼び出しその結果を返す.

  * Returns an object of the same type as ARG0. Each member of the returned object is the return value of a function call where the first argument is the member of ARG0 corresponding to the member in the returned object and the rest of the argument are ARG1, ....

  * FUNCTION is a function name itself without ".

  * A program variable cannot be used as FUNCTION.

  * If ARG0 is neither list nor array this function simply returns the value of FUNCTION(ARG0,ARG1,...).

     [82] def afo(X) { return X^3; }
     [83] map(afo,[1,2,3]);
     [1,8,27]

flist
-----

flist()
     :: 現在定義されている函数名を文字列リストとして返す.

     :: Returns the list of function names currently defined.

return
     文字列のリスト

     list of character strings

  * 現在定義されている組み込み函数, ユーザ定義函数の函数名を文字列リストとして返す.

  * システム函数の後にユーザ定義函数が続く.

  * Returns the list of names of built-in functions and user defined functions currently defined. The return value is a list of character strings.

  * The names of built-in functions are followed by those of user defined functions.

     [77] flist();
     [defpoly,newalg,mainalg,algtorat,rattoalg,getalg,alg,algv,...]

delete_history
--------------

delete_history([INDEX])
     :: ヒストリを消去する.

     :: Deletes the history.

return
     0

index
     消去したいヒストリの番号

     Index of history to be deleted.

  * 引数がないとき, これまで計算したヒストリを全て消去する.

  * 引数があるとき, その番号の結果のみ消去する.

  * ここでヒストリとは, 番号つきのプロンプトに対しての入力を評価して得られた式で, この式は @NUMBER により取り出すことができる. このことは, ガーベッジコレクションの際にもこの式が生き残ることを意味する.

  * 大きな式がヒストリとして残った場合, 以降のメモリ管理に支障を来す場合が多いため, bsave() などでファイルにセーブして, delete_history() によりヒストリを消去しておくのが有効である.

  * Deletes all the histories without an argument.

  * Deletes the history with index INDEX if specified.

  * A history is an expression which has been obtained by evaluating an input given for a prompt with an index. It can be taken out by @INDEX, which means that the expression survives garbage collections.

  * A large history may do harm in the subsequent memory management and deleting the history by delete_history(), after saving it in a file by bsave(), is often effective.

     [0] (x+y+z)^100$
     [1] @0;
     ...
     [2] delete_history(0);
     [3] @0;
     0

get_rootdir
-----------

get_rootdir()
     :: Asir のルートディレクトリ名を取り出す

     :: Gets the name of Asir root directory.

return
     文字列

     string

  * UNIX 版の場合, 環境変数 ASIR_LIBDIR が定義されている場合にはその値, されていない場合には /usr/local/lib/asir を返す.

  * Windows 版の場合, asirgui.exe のあるディレクトリ (bin という名前のはずである) の親ディレクトリが返される.

  * この関数が返すディレクトリ名を基準とした相対パス名を指定することにより, インストールされた場所によらないファイル読み込みプログラムを書くことができる.

  * On UNIX it returns the value of an environment variable ASIR_LIBDIR or /usr/local/lib/asir if ASIR_LIBDIR is not set.

  * On Windows the name of Asir root directory is returned.

  * By using relative path names from the value of this function, one can write programs which contain file operations independent of the install directory.

getopt
------

getopt(KEY)
     :: オプションの値を返す.

     :: Returns the value of an option.

return
     オブジェクト

     object

  * ユーザ定義関数は, 固定個数引数でしか宣言できない. ユーザ定義関数で可変個引数を実現する方法の一つとして, オプションによる引数の指定がある (see オプション指定). 指定されたオプションを関数内で受け取るためにこの関数を用いる.

  * 関数呼び出しの際に KEY がオプションとして指定されている場合には, その値を返す. もし指定がない場合には, VOID 型オブジェクト (型識別子 -1) を返す. getopt() が返した値の型を type() で調べることで, そのオプションが指定されたかどうか調べることができる.

  * 関数呼び出しにおけるオプションの指定は, 正規の引数ならびの後ろに,

          xxx(A,B,C,D|x=X,y=Y,z=Z)

     という風に, | に続く, KEY=VALUE の , で区切られた並びを置くことで行う.

  * When a user defined function is called, the number of arguments must be equal to that in the declaration of the function. A function with indefinite number of arguments can be realized by using OPTIONS (see option). The value of a specified option is retrieved by getopt.

  * If an option KEY is specified upon a function call, getopt return the value of the option. If such an option is not specified, the it returns an object of VOID type whose object identifier is -1. By examining the type of the returned value with type(), one knows whether the option is set or not.

  * Options are specified as follows:

          xxx(A,B,C,D|x=X,y=Y,z=Z)

     That is, the options are specified by a sequence of KEY=VALUE seperated by ,, after |.

参照

References

     オプション指定, type.

     option, type.

getenv
------

getenv(NAME)
     :: 環境変数の値を返す.

     :: Returns the value of an environment variable.

return
name
     文字列

     string

  * 環境変数 NAME の値を返す.

     Returns the value of an environment variable NAME.

     [0] getenv("HOME");
     /home/pcrf/noro