doc/info/Runtime.texi

   1 @menu
   2 * Introduction for Runtime Environment::
   3 * Interrupts::
   4 * Functions and Variables for Runtime Environment::
   5 @end menu
   6
   7 @c -----------------------------------------------------------------------------
   8 @node Introduction for Runtime Environment, Interrupts, Runtime Environment, Runtime Environment
   9 @section Introduction for Runtime Environment
  10 @c -----------------------------------------------------------------------------
  11
  12 @c THIS DISCUSSION OF maxima-init.mac REPLACES AN EARLIER WRITE-UP. !!!
  13 @c HOWEVER IT SEEMS THAT THIS TEXT REALLY WANTS TO BE UNDER A DIFFERENT HEADING. !!!
  14 @code{maxima-init.mac} is a file which is loaded automatically when Maxima
  15 starts.  You can use @code{maxima-init.mac} to customize your Maxima
  16 environment.  @code{maxima-init.mac}, if it exists, is typically placed in the
  17 directory named by @code{maxima_userdir},
  18 although it can be in any directory searched by the function @code{file_search}.
  19
  20 Here is an example @code{maxima-init.mac} file:
  21
  22 @example
  23 setup_autoload ("specfun.mac", ultraspherical, assoc_legendre_p);
  24 showtime:all;
  25 @end example
  26
  27 In this example, @code{setup_autoload} tells Maxima to load the
  28 specified file
  29 (@code{specfun.mac}) if any of the functions (@code{ultraspherical},
  30 @code{assoc_legendre_p}) are called but not yet defined.
  31 Thus you needn't remember to load the file before calling the functions.
  32
  33 The statement @code{showtime: all} tells Maxima to set the @code{showtime}
  34 variable.  The @code{maxima-init.mac} file can contain any other assignments or
  35 other Maxima statements.
  36
  37 @opencatbox
  38 @category{Session management}
  39 @closecatbox
  40
  41 @c -----------------------------------------------------------------------------
  42 @node Interrupts, Functions and Variables for Runtime Environment, Introduction for Runtime Environment, Runtime Environment
  43 @section Interrupts
  44 @c -----------------------------------------------------------------------------
  45
  46 The user can stop a time-consuming computation with the
  47 ^C (control-C) character.
  48 The default action is to stop the computation
  49 and print another user prompt.
  50 In this case, it is not possible to restart a stopped computation.
  51
  52 If the Lisp variable @code{*debugger-hook*} is set to @code{nil}, by executing
  53
  54 @example
  55 :lisp (setq *debugger-hook* nil)
  56 @end example
  57
  58 @noindent
  59 then upon receiving ^C, Maxima will enter the Lisp debugger,
  60 and the user may use the debugger to inspect the Lisp environment.
  61 The stopped computation can be restarted by entering
  62 @code{continue} in the Lisp debugger.
  63 The means of returning to Maxima from the Lisp debugger
  64 (other than running the computation to completion)
  65 is different for each version of Lisp.
  66
  67 On Unix systems, the character ^Z (control-Z) causes Maxima
  68 to stop altogether, and control is returned to the shell prompt.
  69 The @code{fg} command causes Maxima
  70 to resume from the point at which it was stopped.
  71
  72 @opencatbox
  73 @category{Console interaction}
  74 @closecatbox
  75
  76 @c end concepts Runtime Environment
  77
  78 @c -----------------------------------------------------------------------------
  79 @node Functions and Variables for Runtime Environment,  , Interrupts, Runtime Environment
  80 @section Functions and Variables for Runtime Environment
  81 @c -----------------------------------------------------------------------------
  82
  83 @c -----------------------------------------------------------------------------
  84 @anchor{maxima_tempdir}
  85 @defvr {System variable} maxima_tempdir
  86
  87 @code{maxima_tempdir} names the directory in which Maxima creates some temporary
  88 files.  In particular, temporary files for plotting are created in
  89 @code{maxima_tempdir}.
  90
  91 The initial value of @code{maxima_tempdir} is the user's home directory, if
  92 Maxima can locate it; otherwise Maxima makes a guess about a suitable directory.
  93
  94 @code{maxima_tempdir} may be assigned a string which names a directory.
  95
  96 @opencatbox
  97 @category{Global variables}
  98 @closecatbox
  99 @end defvr
 100
 101 @c -----------------------------------------------------------------------------
 102 @anchor{maxima_userdir}
 103 @defvr {System variable} maxima_userdir
 104
 105 @code{maxima_userdir} names a directory which Maxima searches to find Maxima and
 106 Lisp files.  (Maxima searches some other directories as well;
 107 @code{file_search_maxima} and @code{file_search_lisp} are the complete lists.)
 108
 109 The initial value of @code{maxima_userdir} is a subdirectory of the user's home
 110 directory, if Maxima can locate it; otherwise Maxima makes a guess about a
 111 suitable directory.
 112
 113 @code{maxima_userdir} may be assigned a string which names a directory.
 114 However, assigning to @code{maxima_userdir} does not automatically change
 115 @code{file_search_maxima} and @code{file_search_lisp};
 116 those variables must be changed separately.
 117
 118 @opencatbox
 119 @category{Global variables}
 120 @closecatbox
 121 @end defvr
 122
 123 @c -----------------------------------------------------------------------------
 124 @anchor{room}
 125 @deffn  {Function} room @
 126 @fname{room} () @
 127 @fname{room} (true) @
 128 @fname{room} (false)
 129
 130 Prints out a description of the state of storage and
 131 stack management in Maxima.  @code{room} calls the Lisp function of
 132 the same name.
 133
 134 @itemize @bullet
 135 @item
 136 @code{room ()} prints out a moderate description.
 137 @item
 138 @code{room (true)} prints out a verbose description.
 139 @item
 140 @code{room (false)} prints out a terse description.
 141 @end itemize
 142
 143 @opencatbox
 144 @category{Debugging}
 145 @closecatbox
 146 @end deffn
 147
 148 @c -----------------------------------------------------------------------------
 149 @anchor{sstatus}
 150 @deffn {Function} sstatus (@var{keyword}, @var{item})
 151
 152 When @var{keyword} is the symbol @code{feature}, @var{item} is put on the list
 153 of system features.  After @code{sstatus (keyword, item)} is executed,
 154 @code{status (feature, item)} returns @code{true}.  If @var{keyword} is the
 155 symbol @code{nofeature}, @var{item} is deleted from the list of system features.
 156 This can be useful for package writers, to keep track of what features they have
 157 loaded in.
 158
 159 See also @code{status}.
 160
 161 @opencatbox
 162 @category{Programming}
 163 @closecatbox
 164 @end deffn
 165
 166 @c -----------------------------------------------------------------------------
 167 @anchor{status}
 168 @deffn  {Function} status @
 169 @fname{status} (@code{feature}) @
 170 @fname{status} (@code{feature}, @var{item})
 171
 172 Returns information about the presence or absence of certain system-dependent
 173 features.
 174
 175 @itemize @bullet
 176 @item
 177 @code{status (feature)} returns a list of system features. These include Lisp
 178 version, operating system type, etc. The list may vary from one Lisp type to
 179 another.
 180
 181 @item
 182 @code{status (feature, item)} returns @code{true} if @var{item} is on the
 183 list of items returned by @code{status (feature)} and @code{false} otherwise.
 184 @code{status} quotes the argument @var{item}. The quote-quote operator
 185 @code{'@w{}'} defeats quotation. A feature whose name contains a special
 186 character, such as a hyphen, must be given as a string argument. For example,
 187 @code{status (feature, "ansi-cl")}.
 188 @end itemize
 189
 190 See also @code{sstatus}.
 191
 192 The variable @code{features} contains a list of features which apply to
 193 mathematical expressions. See @code{features} and @code{featurep} for more
 194 information.
 195
 196 @opencatbox
 197 @category{Programming}
 198 @closecatbox
 199 @end deffn
 200
 201 @c NEEDS CLARIFICATION
 202
 203 @c -----------------------------------------------------------------------------
 204 @anchor{system}
 205 @deffn {Function} system (@var{command})
 206
 207 Executes @var{command} as a separate process.  The command is passed to the
 208 default shell for execution.  @code{system} is not supported by all operating
 209 systems, but generally exists in Unix and Unix-like environments.
 210
 211 Supposing @code{_hist.out} is a list of frequencies which you wish to plot as a
 212 bar graph using @code{xgraph}.
 213
 214 @example
 215 (%i1) (with_stdout("_hist.out",
 216            for i:1 thru length(hist) do (
 217              print(i,hist[i]))),
 218        system("xgraph -bar -brw .7 -nl < _hist.out"));
 219 @end example
 220
 221 In order to make the plot be done in the background (returning control to
 222 Maxima) and remove the temporary file after it is done do:
 223
 224 @example
 225 system("(xgraph -bar -brw .7 -nl < _hist.out;  rm -f _hist.out)&")
 226 @end example
 227 @end deffn
 228
 229 @c -----------------------------------------------------------------------------
 230 @anchor{time}
 231 @deffn {Function} time (%o1, %o2, %o3, @dots{})
 232
 233 Returns a list of the times, in seconds, taken to compute the output lines
 234 @code{%o1}, @code{%o2}, @code{%o3}, @dots{} The time returned is Maxima's
 235 estimate of the internal computation time, not the elapsed time.  @code{time}
 236 can only be applied to output line variables; for any other variables,
 237 @code{time} returns @code{unknown}.
 238
 239 Set @code{showtime: true} to make Maxima print out the computation time
 240 and elapsed time with each output line.
 241
 242 @opencatbox
 243 @category{Debugging}
 244 @closecatbox
 245 @end deffn
 246
 247 @c -----------------------------------------------------------------------------
 248 @anchor{timedate}
 249 @deffn  {Function} timedate @
 250 @fname{timedate} () @
 251 @fname{timedate} (@var{T})
 252
 253 @code{timedate()} with no argument
 254 returns a string representing the current time and date.
 255 The string has the format @code{YYYY-MM-DD HH:MM:SS[+|-]ZZ:ZZ},
 256 where the fields are year, month, day, hours, minutes, seconds, and time zone
 257 offset in hours and minutes.
 258
 259 @code{timedate(@var{T})} returns the time @var{T}
 260 as a string with the format @code{YYYY-MM-DD HH:MM:SS[+|-]ZZ:ZZ}.
 261 @var{T} is interpreted as the number of seconds since midnight, January 1, 1900,
 262 as returned by @code{absolute_real_time}.
 263
 264 Example:
 265
 266 @code{timedate} with no argument returns a string representing the current time and date.
 267
 268 @c ===beg===
 269 @c d : timedate ();
 270 @c print ("timedate reports current time", d) $
 271 @c ===end===
 272 @example
 273 (%i1) d : timedate ();
 274 (%o1)                      2010-06-08 04:08:09+01:00
 275 (%i2) print ("timedate reports current time", d) $
 276 timedate reports current time 2010-06-08 04:08:09+01:00
 277 @end example
 278
 279 @code{timedate} with an argument returns a string representing the argument.
 280
 281 @c ===beg===
 282 @c timedate (0);
 283 @c timedate (absolute_real_time () - 7*24*3600);
 284 @c ===end===
 285 @example
 286 (%i1) timedate (0);
 287 (%o1)                      1900-01-01 01:00:00+01:00
 288 (%i2) timedate (absolute_real_time () - 7*24*3600);
 289 (%o2)                      2010-06-01 04:19:51+01:00
 290 @end example
 291
 292 @opencatbox
 293 @category{Time and date functions}
 294 @closecatbox
 295 @end deffn
 296
 297 @c -----------------------------------------------------------------------------
 298 @anchor{absolute_real_time}
 299 @deffn {Function} absolute_real_time ()
 300
 301 Returns the number of seconds since midnight, January 1, 1900 UTC.
 302 The return value is an integer.
 303
 304 See also @code{elapsed_real_time} and @code{elapsed_run_time}.
 305
 306 Example:
 307
 308 @c ===beg===
 309 @c absolute_real_time ();
 310 @c 1900 + absolute_real_time () / (365.25 * 24 * 3600);
 311 @c ===end===
 312 @example
 313 (%i1) absolute_real_time ();
 314 (%o1)                      3385045277
 315 (%i2) 1900 + absolute_real_time () / (365.25 * 24 * 3600);
 316 (%o2)                   2007.265612087104
 317 @end example
 318
 319 @opencatbox
 320 @category{Time and date functions}
 321 @closecatbox
 322 @end deffn
 323
 324 @c -----------------------------------------------------------------------------
 325 @anchor{elapsed_real_time}
 326 @deffn {Function} elapsed_real_time ()
 327
 328 Returns the number of seconds (including fractions of a second)
 329 since Maxima was most recently started or restarted.
 330 The return value is a floating-point number.
 331
 332 See also @code{absolute_real_time} and @code{elapsed_run_time}.
 333
 334 Example:
 335
 336 @c ===beg===
 337 @c elapsed_real_time ();
 338 @c expand ((a + b)^500)$
 339 @c elapsed_real_time ();
 340 @c ===end===
 341 @example
 342 (%i1) elapsed_real_time ();
 343 (%o1)                       2.559324
 344 (%i2) expand ((a + b)^500)$
 345 (%i3) elapsed_real_time ();
 346 (%o3)                       7.552087
 347 @end example
 348
 349 @opencatbox
 350 @category{Time and date functions}
 351 @closecatbox
 352 @end deffn
 353
 354 @c -----------------------------------------------------------------------------
 355 @anchor{elapsed_run_time}
 356 @deffn {Function} elapsed_run_time ()
 357
 358 Returns an estimate of the number of seconds (including fractions of a second)
 359 which Maxima has spent in computations since Maxima was most recently started
 360 or restarted.  The return value is a floating-point number.
 361
 362 See also @code{absolute_real_time} and @code{elapsed_real_time}.
 363
 364 Example:
 365
 366 @c ===beg===
 367 @c elapsed_run_time ();
 368 @c expand ((a + b)^500)$
 369 @c elapsed_run_time ();
 370 @c ===end===
 371 @example
 372 (%i1) elapsed_run_time ();
 373 (%o1)                         0.04
 374 (%i2) expand ((a + b)^500)$
 375 (%i3) elapsed_run_time ();
 376 (%o3)                         1.26
 377 @end example
 378
 379 @opencatbox
 380 @category{Time and date functions}
 381 @closecatbox
 382 @end deffn
 383