6.14 Miscellaneouses

6.14.1 ctrl

ctrl("switch"[,obj])

:: Sets the value of switch.

ctrl()

:: Show the values of switch’s.

ctrl(|desc=1)

:: Show the values of switch’s and short descriptions

return

value of switch

switch

switch name

obj

parameter

• 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 section 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 setbprec 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 section Command line options.

  verbose

  If ‘on’ a warning messages is displayed when a function is redefined.

  quiet_mode

  If 1 is set, the copyright notice has been displayed at boot time.

  prompt

  If the value is 0, then prompt is not output. If the value is 1, then the standard prompt is output. Asir prompt can be customized by giving a C-style format string. Example (for unix asir); ctrl("prompt","\033[32m[%d]:= \033[0m")

  hex

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

  real_digit

  Sets the number of digits used to print a floating double.

  double_output

  If set to 1, any floating double is printed in the style ddd.ddd.

  fortran_output

  If ‘on’ polynomials are displayed in FORTRAN style. That is, a power is represented by ‘**’ instead of ‘^’. The default value is ’off.

  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 section Distributed computation.

  ox_check

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

  ox_exchange_mathcap

  If ’on’ Asir forces the exchange of mathcaps at the communication startup. The default value is ’on’. See section Distributed computation.

  debug_window

  When 1, a debug window pops up. (The default value is 0.)

  no_debug_on_error

  When 1, asir or ox_asir do not get into the debug mode.

  fake_ox_reset

  When 1, the function ox_reset sends ox_shutdown insread of ox_reset to servers which do not implement ox_reset protocol. It is checked by the optional argument (the fourth argument) containing the string "no_ox_reset" of mathcap if ox_reset is implemented or not. When you use ox_pari, it is recommended to set this flag 1. (The default value is 0.) See section Distributed computation.

  parallel_gc

  When the value is 0, GC works in the main thread. When the value is n, GC works in n threads. (Default value depends on a machine.)

  plot_by_bigfloat

  If its value N is not equal to zero, then plotting is done by bigfloat. (The double numbers are used as the default.)

  evalef

  When it is set to 0, the arguments of eval are registered to the list of indeterminants when arguments are no longer to be simplified. For example, when this flag is 0, sin(0.1) is registered to the list of indeterminants when eval(sin(0.1)) is evaluated. When it is set to 1, arguments are numerically evaluated. It is recommended to turn on this option, when you repeat to evaluate elementary functions numerically. (The default value is 0.) See section ord

[1917] ctrl();
[[oxpari_start,0],[oxpari_id,-1],... snip ....,[plot_by_bigfloat,0],[debug_plot,0]]
[1918] map(print,ctrl(|desc=1));
[oxpari_start,0,oxpari starting function.]
[oxpari_id,-1,Id of ox_pari.]
... snip ...
[plot_by_bigfloat,0,If set to 1, computation is done by using MPFR bigfloat functions in ox_plot.]
[debug_plot,0,If set to 1, ox_plot is executed with the message window.]

References

cputime, tstart, tstop, output, pari, setbprec, setprec, eval, deval.

ChangeLog

• See section ChangeLog
• plot_by_bigfloat switch is added on 2017.09.04. The following files are changed.
• 1.54 ctrl.c, 1.14 bf.c, 1.75 tcpf.c, 1.13 calc.c, 1.36 if.c, 1.25 ifplot.h, 1.33 plotf.c

6.14.2 debug

debug

:: Forces to enter into debugging mode.

• 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] 

6.14.3 error

error(message)

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

message

string

• 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.

6.14.4 help

help(["function"])

:: Displays the description of function function.

return

0

function

function name

• 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’.
• If the LANG environment variable is set and its value begins with "japan" or "ja_JP", then the file in ‘help-ja’ is displayed. If its value does not begin with "japan" or "ja_JP", then the file in ‘help-en’ is displayed.
• On Windows HTML-style help is available from the menu.

6.14.5 time

time()

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

return

list

• These are commands regarding CPU time and GC time (the current version adds the GC time to the CPU 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.’ (The current version adds the GC time to the CPU time, then the GC time shows 0.)
• Command time() returns total CPU time and GC time (0 is displayed) 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, currenttime.

6.14.6 cputime, tstart, tstop

cputime(onoff)

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

tstart()

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

tstop()

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

return

0

onoff

flag (arbitrary)

• 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, currenttime, ctrl.

6.14.7 timer

timer(interval,expr,val)

:: Compute an expression under the interval timer.

return

result

interval

interval (second)

expr

expression to be computed

val

a value to be returned when the timer is expired

• timer() computes an expression under the interval timer. If the computation finishes within the specified interval, it returns the result of the computation. Otherwise it returns the third argument.
• The third argument should be distinguishable from the result on success.

[0] load("cyclic");
1
[10] timer(10,dp_gr_main(cyclic(7),[c0,c1,c2,c3,c4,c5,c6],1,1,0),0);
interval timer expired (VTALRM)
0
[11] 

6.14.8 currenttime

currenttime()

:: Get current time.

return

UNIX time.

• See also time(3) in UNIX manuals.

[0] currenttime();
1071639228
[1] 

6.14.9 sleep

sleep(interval)

:: Suspend computation for an interval.

return

1

interval

interval (micro second)

• See also usleep(3) in UNIX manuals.

[0] sleep(1000);
1
[1] 

6.14.10 heap

heap()

:: Heap area size currently in use.

return

non-negative integer

• 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 section 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.

6.14.11 version

version()

:: Version identification number of Asir.

return

integer

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

[0] version();
991214

6.14.12 shell

shell(command)

:: Execute shell commands described by a string command.

return

integer

command

string

• 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] 

6.14.13 map

map(function,arg0,arg1,...)

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

return

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)

• 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]

6.14.14 flist

flist([mname])

:: Returns the list of function names currently defined.

mname

a module name

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. If a module name is specified, only the names of functions defined in the module are returned.
• The names of built-in functions are followed by those of user defined functions.

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

6.14.15 delete_history

delete_history([index])

:: Deletes the history.

return

0

index

Index of history to be deleted.

• 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

6.14.16 get_rootdir

get_rootdir()

:: Gets the name of Asir root directory.

return

string

• 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.

6.14.17 getopt

getopt([key])

:: Returns the value of an option.

return

object

• 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 section option). The value of a specified option is retrieved by getopt.
• If getopt() is called with no argument, then it returns a list [[key1,value1], [key2,value2],…]. In the list, each key is an option which was specified when the function executing getopt was invoked, and value is the value of the option.
• 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 separated by ‘,’, after ‘|’.

References

option, type.

6.14.18 getenv

getenv(name)

:: Returns the value of an environment variable.

return

name

string

• Returns the value of an environment variable name.

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

This document was generated on October 22, 2025 using texi2html 5.0.