Windows installer: Update README.txt.

[maxima.git] / archive / doc / None.texi

@node None, Function and Variable Index, Ctensor, Top
@chapter None
@menu
* Introduction to None::        
* Definitions for None::        
@end menu

@node Introduction to None, Definitions for None, None, None
@section Introduction to None
@section DILOGARITHMS
 - See POLYLOGARITHMS.

@section B
 (%o1)                             (N + 1)!

@section FILE
 - A file specification is a string such as "foo".  You may
also specify just the symbol foo.  So load("foo") and
load(foo) should do the same thing (unless foo has a value).
Symbols will be mapped to lower cases, and strings left alone.
There are various FILE_SEARCH lists.   see FILE_SEARCH.

@section HACIJAN
 - An implementation of Hacijan's linear programming algorithm
is available by doing BATCH("kach.mc")$.  Details of use are
available by doing BATCH("kach.dem");

@section IMSL
 - For information on MACSYMA-IMSL packages available do:
PRINTFILE(IMSL,USAGE,SHARE2); IMSL-based routines currently return
[SUCCESS, ...] or [ERROR, ...].  They will soon be changed to return
[SUCCESS, ...], [WARNING, ...] and [ERROR, ...].

@section INDEX_FILE_DIM
 ,symbol-returned-by-OPEN_INDEX_FILE) - returns an
integer indicating the number of expressions in the indexed file.
See DESCRIBE(OPEN_INDEX_FILE);.

@section IRREDUCIBLE
 - This command has been removed.

@section ITS
 - The operating system under which MACSYMA runs on the MIT-MC
machine.  It stands for "Incompatible Timesharing System".

@section MAP_OVER_INDEX_FILE
 ,|function, fileobject|) is convenient for
generating an index list of properties of the objects in a file vs.
their positions in the file.  See DESCRIBE(MAKE_INDEX_FILE);.

@section MODRESULT
 - This switch is obsolete.  The new RESULTANT switch should
be used.  Do DESCRIBE(RESULTANT); for details.

@section MORE
 Processing - The term used to describe the action of a CRT
console when it stops at the bottom of the screen to allow the user
to finish reading.  See PAGEPAUSE and MOREWAIT for details.

@section NTRIG
 - SHARE1;NTRIG FASL allows MACSYMA to compute trig functions
with arguments of the form N*%PI/10 for integer N.  Do LOAD(NTRIG) to
access this. The main functions are USIN(N) and UCOS(N).

@section NUMERICAL
 - There are a number of packages for numerical methods in
MACSYMA.  See IMSL and the SHARE directories.

@section SET
 - See Sets.

@section STORENUM
 - The value of this variable, an integer, is the second name
of the last file written by the automatic storage scheme.  (See
DESCRIBE(DSKGC)).  Each time a file is written, STORENUM is first
increased by 1, so it must always be an integer.  It is initially set
to 1000.

@section UPDATE
 - The Update file has been moved to the MACDOC directory, so
you should do PRINTFILE(UPDATE,>,MACDOC); to read it.  Also, you may
find information of a useful nature on this directory, so you may want 
to list it (LISTFILES(MACDOC); in MACSYMA) and print some other files
also.
Here follows a list of changes to MACSYMA since the Version 10
manual.  Do DESCRIBE(cmd); to see their documentation:
New Functions or variables: LCM, RNCOMBINE.
New SHARE packages of interest:  ATRIG1, NTRIG.
The following functions have been removed from MACSYMA:  TRIGSUM.

@section ---Begin
 new doc by wfs
@section EDITOR-ZMACS
 The lisp machine version of macsyma contains many helpful
editor commands.  The best way to find out about them is to do Meta-X
Apropos the string "macsyma" since most of the commands involve this
name.  Macsyma Mode is obtained by doing the extended command Macsyma
mode.  When in macsyma mode the keysrokes such as ctrl-shift-C refer to
compiling macsyma code in a marked region, or else between the $ or ;
delimiters if no region is marked.

It is possible to evaluate expressions into the buffer by typing
control-shift-I (for example a line label %o3 has a value you want to
alter).  The macsyma evaluator will be called on the current region and
the result will be ground into the buffer.  It can then be altered and
reevaluated by using control-shift-E to evaluate it.


@section FILENAMES--lispm
   Since source files for Macsyma on the lisp machines
will often be on many different machines, it is difficult to have a good
file search mechanism.  The best thing for a user to do is to specify a
file name as a string, as fully as he finds necessary.  The syntax
should be that of the machine on which the file resides.  For example
BATCH("/home/wfs/test.mac") or
DEMO("/home/wfs/defint.dmo") are valid specifications, for a
Using the input editor long pathnames are typed rather easily,
and of course there is always the option of defining a logical pathname
to stand for them.

The current logical pathnames for the sources should be
"Maxima-source:maxima;foo.lisp".

@section FUNCTION-ARGUMENTS
 To find the function argument of a function when in
the input editor of a macsyma listener you may type Control-meta-A when
the cursor is placed just after the name of the function.  Unfortunately
some macsyma functions use variable names which are not very suggestive.
If a function takes keyword arguments, these can be entered at macsyma
level by typing ?:..  . For example if you want to call the common lisp
function member which takes a keyword test you would enter

 AA:MAKE_HASH_TABLE(?:TEST,?EQL); 

This will use the lisp function eql for comparison of entries in AA.
AA[1]:2;
AA[1]; ==> 2.

@section MACSYMA-LISTENER
 Select A (or System A) selects the most current 
macsyma listener.  You may also click on the system menu, and create
new different shaped listeners.   The line labels are shared among 
the listeners, so that you may refer to line labels defined in one
window, in another window.  

Enabling or disabling more-processing (the pause at the end of a page of
display) is done as with lisp listeners (eg. use the function key).

@section HELP--see
:documentation  

@section  XXX



@c end concepts None
@node Definitions for None,  , Introduction to None, None
@section Definitions for None
@defun COMPRESS
 - This command has been withdrawn, see COLLAPSE.

@end defun
@defun COMPRESS_FILE
 - This command has been withdrawn, see COLLAPSE.

@end defun
@defvar CURSOR
 default: [$] is the prompt symbol of the MACSYMA editor.

@end defvar
@defun DISKUSE 
(username) returns the total number of disk blocks in use by a
user.  The result is of the form <n>*BLOCKS

@end defun
@defvar DOVARD_VIEWPORT
 default: [1,7,1,7] determines the perspective for
Dover output plots, similar to VIEWPT.  It accepts 4 arguments,
[XMIN,XMAX,YMIN,YMAX] in inches on the page.

@end defvar
@defvar DSKGC
 default: [FALSE] if TRUE will cause user defined values,
functions, arrays, and line labelled expressions to be automatically
stored on disk whenever the system determines that the available
in-core space is getting low.  (For historical reasons this is also
a function, but it should be used as a switch.  Please use it as
described here, not as a function.)

@end defvar
@defvar DSKUSE
 default: [FALSE] if TRUE, from this point in the computation
on labelled expressions will be written out periodically onto the
disk.  (A labelled expression is one which is referred to by a line
label, e.g. %o4, %i7, %t12.)  Once an expression is written onto the disk
it will no longer reside in main memory and most of the main memory
storage taken up by it will be released. When the user attempts to
reference an expression which has been stored onto the disk, MACSYMA
will retrieve the correct value from the disk file.

@end defvar
@defvar DYNAMALLOC
 default: [FALSE] if TRUE will allocate additional space
whenever necessary.

@end defvar
@defun ED 
() - calls the NIL editor, which is called STEVE.  STEVE is an editor
for CRT consoles, which is best at speeds of 1200 baud or greater.
The interface it presents is close to that of the EMACS editor used
on the TOPS-20 and ITS operating systems.  Doing
        TEACH_STEVE();
will run a tutorial on the editor.   At this time it is unfortunately
not possible to either "zap" an expression from a command line into
the editor, nor to "zap" an edited expression back to MACSYMA for
evaluation;  however, the editor can be used for file editing.
DESCRIBE(EDITOR) for information about the MACSYMA line editor.

@end defun
@defun EDITOR
 - There is a line editor in MACSYMA, which you may enter by typing
an altmode (the "esc" key on most consoles) for PDP-10 and NIL versions
of MACSYMA, and & (ampersand) for Multics.  Your current command line
will be automatically brought into the editor for you to edit.  Commands
are terminated by two altmodes (two &'s on Multics).  An additional
two altmodes will return you to MACSYMA with the edited string on your
command line.
Some useful commands:
Command         Action
-------         ______
nC              moves the cursor past n characters.
nR              moves the cursor past n characters in the
                 reverse direction (nR = -nC).
nSstring<$>     moves the cursor to the right (left if n is
                 negative) of the nth occurrence of "string" in
                 the input string.
) or ]          moves the cursor right from the current position
                 over the next balanced pair of parentheses (or
                 brackets).
( or [          similar to ) or ] but moves left.
nD              deletes n characters, and saves them in the
                 "save-register" (see the GR command below).
nK              deletes all the characters through the nth carriage return
                 (0K kills left), and saves them in the "save-register";
                 e.g., K deletes the remainder of this line.
Istring<$>      inserts the characters "string" at the current cursor
                 position.  The cursor is positioned at the right of
                 the inserted text.  If no argument is given then the
                 string of the last I command which had one is used.
GR              inserts at the current cursor position the characters
                 deleted by the last use of D or K.  Thus GR may be used
                 in combination with D or K to move characters from one
                 place to another in the input string; or to recover
                 from an accidental use of D or K.  There is only one
                 "save-register".

@end defun
@defun EMACS 
() - calls the NIL editor.  DESCRIBE(ED) for more information.
The name EMACS derives from the editor of that name used on the ITS
and TOPS-20 operating systems.

@end defun
@defun FILEOP
 - SHARE;FILEOP -- some file primitives for MC Macsyma users.
Macsyma now provides some useful simple file primitives which were
formerly only available in other system programs.
To print the contents of a file on your terminal, say
PRINTFILE(file,name,dsk,me);
To list your directory, say LISTFILES(dsk,me).  If you use a shared
directory such as USERS or PLASMA, only your files--the ones
with your login name as first file name--will be shown.
The length and date of creation of each file is also shown.
The function FILELENGTH returns the length of the file argument
in blocks and fractional blocks.
In order to list just the names of your files without the
length and date information, use QLISTFILES (Quick LIST Files)
with the same arguments as LISTFILES.
The function RENAMEFILE(oldname,newname) renames a file from oldname
to newname.
Details.
The PRINTFILE command takes the same argument syntax as LOADFILE;
the other two take the syntax of WRITEFILE.  LISTFILES indicates
whether each file is stored on secondary disk and whether it
has been backed up to tape (an exclamation point appears if
it has not).
The FILELENGTH command returns the length in blocks and fractional
blocks: there are five characters in a word and 1024 words in a disk block.
(So if it returns 5.6, the file is 6 blocks long, but the last block
is only 60% full.  This file would be 5.6*1024*5 (= 28672) characters
long.)  If the file named does not exist, an error message is printed,
and False is returned to permit easier recovery in a program.
Files may not be renamed across directories or devices. Both oldname
and newname must be on the same directory. Renaming a file to a filename
that already exists gives an error. You must explicitly DELFILE the
existing file first if that's what you want.  Both oldname and newname
must be list-type filespecs. example: 
RENAMEFILE([myold,file,dsk,foo],[mynew,file]);

@end defun
@defvar FILESIZE
 default: [] - The value of this variable is the number of
expressions written into each file by the automatic disk storage
scheme.  The default value is 16.

@end defvar
@defun FULLDISKUSE 
(username) If no name is supplied, it defaults to the
current user's.  Returns long list of info about user's disk usage of
the form:
  [["TOTAL FREE BLOCKS", [<pack-type>, <pack-number>, <n> BLOCKS],
                         [<pack-type>, <pack-number>, <n> BLOCKS], ...]
   ["DIRECTORY BLOCK USAGE", <directory-name>
                             ["PRIMARY", <n> BLOCKS],
                             ["SECONDARY", <n> BLOCKS]]
   ["USER BLOCK USAGE", <user-name>,
                        [PRIMARY, <n> BLOCKS],
                        [SECONDARY, <n> BLOCKS]]]
If the user has his own directory, the last element of the list ("USER
BLOCK USAGE") is omitted since it would be the same as "DIRECTORY
BLOCK USAGE".
        <pack-type> ::= "PRIMARY PACK" or "SECONDARY PACK"
        <pack-number> ::= a fixed point number
        <n> ::= a fixed point number
Occurrences of `<n> BLOCKS' are in the form of a Macsyma multiplication
between a fixnum <n> and the Macsyma symbol BLOCKS.

@end defun
@defun DIRECTORY(path)
List files in path.   Path may be something like "/home/wfs/*.mac"


@end defun
@defun LOGOUT 
() - causes the user to be logged out and all jobs deleted.
This is useful when it is desired to BATCH in a file and have the
terminal logged out automatically when the computations are finished.
This causes the process which invoked MACSYMA to execute a LOGOUT
command.

@end defun
@defun MAIL 
("message") will send mail to MACSYMA.  This may be used to report
problems or bugs.
MAIL(username,"message") will send mail to a specific user.
Expressions may be included by referring to them, outside double
quotes, when (and only when) a username is given, e.g.
MAIL(ELLEN,"I am trying to integrate",%o3,"but it asks for more list
space.  What should I do?");
Not supported yet in NIL Macsyma.

@end defun
@defun MAKE_INDEX_FILE 
("filename"); will parse a batch file without
evaluating it.  This is useful for debugging init files.  See
DESCRIBE(init); and DESCRIBE(OPEN_INDEX_FILE);.

@end defun
@defvar MOREWAIT
 default: [FALSE] - Controls the action of more processing.
Currently in NIL Macsyma, the setting of this has no effect.
When output is suspended and a --Pause-- or --More Display?-- prompt
is issued, one may type a space to continue the output.  Typing any
character other than space or rubout (delete) will continue the output,
and leave the character around to be read as part of the next c-line
and possibly intervening --Pause-- prompts.

@end defvar


@end defun

@end defun
@defvar PAGEPAUSE
 default: [] - This is set by MACSYMA according to what the
system knows about your terminal type.  If it is set to TRUE, then
"more" processing, which involves the printing of --More display?-- or
--Pause-- at the bottom of your screen or after so many lines on a
printing terminal, and pausing, will be enabled.  It may be set to
FALSE to turn off the "more" processing on a display terminal.
PAGEPAUSE is sometimes useful in batch files on slow lines where you
just wish to watch the output run past, and can keep up with the line
speed well enough.

@end defvar
@defun PAUSE 
() - Causes the display to "pause", printing "--Pause--" and
waiting for the usual "space" for "yes" to resume printing.  Then it
clears the screen and continues.  PAUSE("--Something else--"); will
use "--Something else--" as the string printed instead of "--Pause--".
PAUSE("--Something else--","--And some more--"); will use "--Something
else--" instead of "--Pause--" and "--And some more--" instead of
"--Continued--".

@end defun

@defun RENAMEFILE 
(oldfilename, newfilename) - Gives a new name to a file.
Oldfilename may name any file. It should use the list filename format
- eg, [MYOLD,FILE,DSK,USERS5].  Newfilename must be a filename on the
same device and directory.  Hence only filename1 and filename2 should
be specified.  For example, [MYNEW,FILE].  Attempting to change the
name of a file that does not exist, or to rename a file to the name of
a file that exists already will generate an error; hence, it is not
possible to inadvertently destroy a file using this command.

@end defun

@defun TAG_FILE_INSERT 
(file-to-insert-into, file-to-insert) - Inserts a file
created by the translator into a multiple entry tags file.

@end defun
@defun TIMEDATE 
() prints out the current date and time.

@end defun

@defvar VERSION
 default: [5,4,"Wed Oct ..."] - are the major and minor versions of MAXIMA.
This could be useful if the user wants to label his output, or to associate
bugs with a particular version.

@end defvar

@c BEGIN ITEMS CUT FROM Input.texi 20041031
@defun BACKUP ()
To "back up" and see what you did, see PLAYBACK.

@end defun

@defvar BATCHKILL
 default: [FALSE] if TRUE then the effect of all previous
BATCH files is nullified because a KILL(ALL) and a RESET() will be
done automatically when the next one is read in.  If BATCHKILL is
bound to any other atom then a KILL of the value of BATCHKILL will be
done.

@end defvar

@defun BATCON (argument)
continues BATCHing in a file which was interrupted.

@end defun

@defvar BATCOUNT
 default: [0] may be set to the number of the last expression
BATCHed in from a file.  Thus BATCON(BATCOUNT-1) will resume BATCHing
from the expression before the last BATCHed in from before.

@end defvar

@defvar CHANGE_FILEDEFAULTS
 default: [TRUE] on PDP10 systems, and FALSE
elsewhere.  Controls whether the user doing a LOADFILE or BATCH has
his file defaults changed to the file LOADFILEd or BATCHed.  The TRUE
setting is for people who like DDT-style file defaulting.  The FALSE
setting is for people who like the conventions of other operating
systems, who like LISP-style file defaulting, or who write packages
which do LOADFILEs or BATCHes which should not interfere with their
user's file defaults.

@end defvar

@defvar DIREC
 - The value of this variable is the default file directory for
SAVE, STORE, FASSAVE, and STRINGOUT.  It is initialized to the user's
login name, if he has a disk directory, and to one of the USERSi
directories otherwise.  DIREC determines to what directory disk files
will be written.

@end defvar

@defvar DSKALL
 default: [] If TRUE will cause values, functions, arrays, and
rules to be written periodically onto the disk in addition to labelled
expressions.  TRUE is the default value whereas if DSKALL is FALSE
then only labelled expresions will be written.

@end defvar

@defvar FILENAME
 default: [] - The value of this variable is the first name
of the files which are generated by the automatic disk storage scheme.
The default value is the first three characters of the user's login
name concatenated with the lowest unused integer, e.g. ECR1.

@end defvar

@defvar FILENUM
 default: [0] - The default second file name for files generated
by SAVE, STRINGOUT, or FASSAVE if no file names are specified by the
user.  It is an integer, and is incremented by one each time a new file
is written.

@end defvar

@defvar FILE_STRING_PRINT
 default: [FALSE] on MC, [TRUE] elsewhere.  If
TRUE, filenames are output as strings; if FALSE, as lists.  For
example, the message when an out of core file is loaded into
MACSYMA (e.g. the LIMIT package), appears on MC in list format as
  LIMIT FASL DSK MACSYM being loaded
and in string format as:
  DSK:MACSYM;LIMIT FASL being loaded
The string format is like the top level (DDT) file specifications.

@end defvar

@defvar LINEDISP
 default: [TRUE] - Allows the use of line graphics in the
drawing of equations on those systems which support them (e.g. the
Lisp Machine).  This can be disabled by setting LINEDISP to FALSE.  It
is automatically disabled during WRITEFILE.

@end defvar

@defun NOSTRING (arg)
displays all input lines when playing back rather than
STRINGing them.  If arg is GRIND then the display will be in a more
readable format.  One may include any number of options as in
PLAYBACK([5,10],20,TIME,SLOW).

@end defun

@defvar PARSEWINDOW
 default:[10] - the maximum number of "lexical tokens"
that are printed out on each side of the error-point when a syntax
(parsing) error occurs.  This option is especially useful on slow
terminals.  Setting it to -1 causes the entire input string to be
printed out when an error occurs.

@end defvar

@defun SPRINT (exp1, exp2, ...)
evaluates and displays its arguments one
after the other "on a line" starting at the leftmost position.  The
numbers are printed with the '-' right next to the number, and
it disregards line length.   
@end defun
@c END ITEMS CUT FROM Input.texi 20041031

@c BEGIN TEXT RECENTLY (200410) CUT FROM doc/info/Program.texi
@defun LISPDEBUGMODE ()
LISPDEBUGMODE(); DEBUGPRINTMODE(); and DEBUG();
make available to the user debugging features used by systems
programmers.  These tools are powerful, and although some conventions
are different from the usual macsyma level it is felt their use is
very intuitive.  [Some printout may be verbose for slow terminals,
there are switches for controlling this.]  These commands were
designed for the user who must debug translated macsyma code, as such
they are a boon.  See MACDOC;TRDEBG USAGE for more information.

@end defun
@c END TEXT RECENTLY (200410) CUT FROM doc/info/Program.texi

@c BEGIN TEXT RECENTLY (200410) CUT FROM doc/info/Command.texi
@defvar LASTTIME
 - the time to compute the last expression in milliseconds
presented as a list of "time" and "gctime".

@end defvar

@defun TOBREAK ()
causes the MACSYMA break which was left by typing
TOPLEVEL; to be re-entered.  If TOBREAK is given any argument
whatsoever, then the break will be exited, which is equivalent to
typing TOBREAK() immediately followed by EXIT;.

@end defun

@defun TOPLEVEL ()
During a break one may type TOPLEVEL;.  This will cause
top-level MACSYMA to be entered recursively.  Labels will now be bound
as usual.  Everything will be identical to the previous top-level
state except that the computation which was interrupted is saved.  The
function TOBREAK() will cause the break which was left by typing
TOPLEVEL; to be re-entered.  If TOBREAK is given any argument
whatsoever, then the break will be exited, which is equivalent to
typing TOBREAK() immediately followed by EXIT;.

@end defun

@defvar TTYINTFUN
 default: [FALSE] - Governs the function which will be run
whenever the User-interrupt-character is typed.  To use this feature,
one sets TTYINTFUN (default FALSE meaning feature not in use) to a
function of no arguments.  Then whenever (e.g.) ^U (control-U) is
typed, this function is run.  E.g. suppose you have a FOR statement
loop which increments I, and you want an easy way of checking on the
value of I while the FOR statement is running.  You can do:
TTYINTFUN:PRINTI$ PRINTI():=PRINT(I)$ , then whenever you type (e.g.)
^U you get the check you want.

@end defvar

@defvar TTYINTNUM
 default: [21] (the ascii value of Control-U (^U), U being
the 21st letter of the alphabet).  This controls what character
becomes the User-interrupt-character.  ^U was chosen for it mnemonic
value.  Most users should not reset TTYINTNUM unless they are already
using ^U for something else.

@end defvar
@c END TEXT RECENTLY (200410) CUT FROM doc/info/Command.texi

@c BEGIN TEXT RECENTLY (200410) CUT FROM doc/info/Runtime.texi
@defun CONTINUE
 - Control-^ typed while in MACSYMA causes LISP to be
entered.  The user can now type any LISP S-expression and have it
evaluated.  Typing (CONTINUE) or ^G (control-G) causes MACSYMA to be
re-entered.

@end defun

@defun ALARMCLOCK (arg1, arg2, arg3)
will execute the function of no
arguments whose name is arg3 when the time specified by arg1 and arg2
elapses.  If arg1 is the atom "TIME" then arg3 will be executed after
arg2 seconds of real-time has elapsed while if arg1 is the atom
"RUNTIME" then arg3 will be executed after arg2 milliseconds of cpu
time. If arg2 is negative then the arg1 timer is shut off.

@end defun

@defun ALLOC
 takes any number of arguments which are the same as the replies
to the "run out of space" question.  It increases allocations
accordingly.  E.g. If the user knows initially that his problem will
require much space, he can say ALLOC(4); to allocate the maximum
amount initially.  See also the DYNAMALLOC switch.

@end defun

@defun BUG ("message")
similar to mail, sends a message to MACSYMA Mail.
This may be used for reporting bugs or suspected bugs in MACSYMA.
Expressions may be included by referring to them, outside double
quotes, e.g.
BUG("I am trying to integrate",%o3,"but it asks for more list space.
What should I do?");

@end defun

@defun DDT ()
Exits from MACSYMA to the operating system level.  (The same
as control-Z on ITS, or control-C on Tops-20.)

@end defun

@defun DELFILE (file-specification)
will delete the file given by the
file-specification (i.e. firstname, secondname, device, user) from the
given device.

@end defun

@defun DISKFREE ()
With no args or an arg of TRUE, will return the total
number of free blocks of disk space in the system.  With an arg of 0,
1, or 13, it will return the number of free blocks of diskspace on the
respective disk pack.  With an arg of SECONDARY or PRIMARY, it will
return the total number of free blocks of disk space on the secondary
or primary disk pack respectively.

@end defun
@c END TEXT RECENTLY (200410) CUT FROM doc/info/Runtime.texi

@defun FASSAVE (args)
is similar to SAVE but produces a FASL file in which
the sharing of subexpressions which are shared in core is preserved in
the file created.  Hence, expressions which have common subexpressions
will consume less space when loaded back from a file created by
FASSAVE rather than by SAVE.  Files created with FASSAVE are reloaded
using LOADFILE, just as files created with SAVE.  FASSAVE returns a
list of the form [<name of file>,<size of file in blocks>,...] where
...  are the things saved.  Warnings are printed out in the case of
large files.  FASSAVE may be used while a WRITEFILE is in progress.

@end defun

@node OPTIMIZATION, Definitions for Function Definition, MACROS, Function Definition
@section OPTIMIZATION

The optimu files no longer exist in Maxima.  The documentation is left 
here for historical purposes.

When using TRANSLATE and generating code with MACSYMA,
there are a number of techniques which can save time and be helpful.
Do DEMO("optimu.dem") for a demonstration.  In particular, the
function FLOATDEFUNK from TRANSL;OPTIMU FASL, creates a function
definition from a math-like expression, but it optimizes it (with
OPTIMIZE) and puts in the MODE_DECLAREations needed to COMPILE
correctly. (This can be done by hand, of course).  The demo will only
run in a fresh macsyma.

@c @node ODE
@c @unnumberedsec phony
@defun ODE (equation,y,x)
This no longer exists in Maxima.  The documentation is left here for
historical purposes.

a pot-pourri of Ordinary Differential solvers
combined in such a way as to attempt more and more difficult methods
as each fails. For example, the first attempt is with ODE2, so
therefore, a user using ODE can assume he has all the capabilities of
ODE2 at the very beginning and if he has been using ODE2 in programs
they will still run if he substitutes ODE (the returned values, and
calling sequence are identical).
In addition, ODE has a number of user features which can assist an
experienced ODE solver if the basic system cannot handle the equation.
The equation is of the same form as required for ODE2 (which see) and
the y and x are dependent and independent variables, as with ODE2.
For more details, do PRINTFILE(ODE,USAGE,SHARE); .

@end defun
@c @node ZRPOLY
@c @unnumberedsec phony
@defun ZRPOLY
 - This is no longer available in Maxima. See ALLROOTS for a function
   to compute the roots of a polynomial.

@c @node ZSOLVE
@c @unnumberedsec phony
@defun ZSOLVE
 This is not available with Maxima anymore.  Documentation is left for
 historical purposes.

 - For those who can make use of approximate numerical
solutions to problems, there is a package which calls a routine which
has been translated from the IMSL fortran library to solve N
simultaneous non-linear equations in N unknowns.  It uses black-box
techniques that probably aren't desirable if an exact solution can be
obtained from one of the smarter solvers (LINSOLVE, ALGSYS, etc).  But
for things that the other solvers don't attempt to handle, this can
probably give some very useful results.  For documentation, do
PRINTFILE("zsolve.usg");.  For a demo do
batch("zsolve.mc")$

@end defun
@section DCADRE
The following is obsolete and does not exist in Maxima 5.9.  We leave
the documentation here for historical purposes.

To make an interface to fortran
libraries in the current Maxima look at the examples in
"maxima/src/fortdef.lsp"
 - The IMSL version of Romberg integration is now available in
Maxima.  For documentation, Do PRINTFILE(DCADRE,USAGE,IMSL1); .  For
a demo, do batch("dcadre.mc");
This is a numerical integration package using cautious, adaptive
Romberg extrapolation.
The DCADRE package is written to call the IMSL fortran library routine
DCADRE. This is documentation for that program. Send bugs/comments to
KMP
To load this package, do 
@example
  LOADFILE("imsl")$
@end example
For a demo of this package, do
@example
  batch("dcadre.mc");
@end example
The worker function takes the following syntax:
IMSL_ROMBERG(fn,low,hi)
where fn is a function of 1 argument; low and hi should be the lower and
upper bounds of integration. fn must return floating point values.
IMSL_ROMBERG(exp,var,low,hi)
  where exp should be integrated over the range var=low to hi. The result
  of evaluating exp must always be a floating point number.
FAST_IMSL_ROMBERG(fn,low,hi)
  This function does no error checking but may achieve a speed gain over
  the IMSL_ROMBERG function. It expects that fn is a Lisp function (or
  translated Maxima function) which accepts a floating point argument 
  and that it always returns a floating point value.
           
Returns either
 [SUCCESS, answer, error] where answer is the result of the integration and
  error is the estimated bound on the absolute error of the output, DCADRE,
  as described in PURPOSE below.
or
 [WARNING, n, answer, error] where n is a warning code, answer is the answer,
  and error is the estimated bound on the absolute error of the output, DCADRE,
  as described in PURPOSE below. The following warnings may occur:
     65 = One or more singularities were successfully handled.
     66 = In some subinterval(s), the estimate of the integral was accepted
          merely because the estimated error was small, even though no regular
          behavior was recognized.
or
 [ERROR, errorcode] where error code is the IMSL-generated 
   error code. The following error codes may occur:
     131 = Failure due to insufficient internal working storage.
     132 = Failure. This may be due to too much noise in function 
           (relative to the given error requirements) or due to an
           ill-behaved integrand.
     133 = RERR is greater than 0.1 or less than 0.0 or is too small
           for the precision of the machine.
  
The following flags have an influence upon the operation of IMSL_ROMBERG --

ROMBERG_AERR [Default 1.0E-5] -- Desired absolute error in answer.

ROMBERG_RERR [Default 0.0] -- Desired relative error in the answer.

Note: If IMSL signals an error, a message will be printed on the user's
        console stating the nature of the error. (This error message 
        may be supressed by setting IMSLVERBOSE to FALSE.)

Note: Because this uses a translated Fortran routine, it may not be
        recursively invoked. It does not call itself, but the user should
        be aware that he may not type ^A in the middle of an IMSL_ROMBERG
        computation, begin another calculation using the same package,
        and expect to win -- IMSL_ROMBERG will complain if it was already
        doing one project when you invoke it. This should cause minimal
        problems.

Purpose (modified version of the IMSL documentation)
----------------------------------------------------

DCADRE attempts to solve the following problem: Given a real-valued 
function F of one argument, two real numbers A and B, find a number

DCADRE such that:

@example
|   / B               |        [                              | / B      | ]
|   [                 |        [                              | [        | ]
|   I F(x)dx - DCADRE | <= max [ ROMBERG_AERR, ROMBERG_RERR * | I F(x)dx | ]
|   ]                 |        [                              | ]        | ]
|   / A               |        [                              | / A      | ]
@end example
Algorithm (modified version of the IMSL documentation)

This routine uses a scheme whereby DCADRE is computed as the sum of
estimates for the integral of F(x) over suitably chosen subintervals of
the given interval of integration. Starting with the interval of
integration itself as the first such subinterval, cautious Romberg
extrapolation is used to find an acceptable estimate on a given
subinterval. If this attempt fails, the subinterval is divided into two
subintervals of equal length, each of which is considered separately.
Programming Notes (modified version of the IMSL documentation)

@itemize @bullet
@item
1. DCADRE (the translated-Fortran base for IMSL_ROMBERG) can, in many cases,
   handle jump discontinuities and certain algebraic discontinuities. See 
   reference for full details.
@item
2. The relative error parameter ROMBERG_RERR must be in the interval [0.0,0.1].
   For example, ROMBERG_RERR=0.1 indicates that the estimate of the intergral 
   is to be correct to one digit, where as ROMBERG_RERR=1.0E-4 calls for four
   digits of accuracy. If DCADRE determines that the relative accuracy
   requirement cannot be satisfied, IER is set to 133 (ROMBERG_RERR should be
   large enough that, when added to 100.0, the result is a number greater than
   100.0 (this will not be true of very tiny floating point numbers due to
   the nature of machine arithmetic)).
@item
3. The absolute error parameter, ROMBERG_AERR, should be nonnegative. In
   order to give a reasonable value for ROMBERG_AERR, the user must know 
   the approximate magnitude of the integral being computed. In many cases,
   it is satisfactory to use AERR=0.0. In this case, only the relative error
   requirement is satisfied in the compuatation.
@item
4. We quote from the reference, ``A very cautious man would accept DCADRE 
   only if IER [the warning or error code] is 0 or 65. The merely reasonable
   man would keep the faith even if IER is 66. The adventurous man is quite 
   often right in accepting DCADRE even if the IER is 131 or 132.'' Even when
   IER is not 0, DCADRE returns the best estimate that has been computed.
@end itemize

For references on this technique, see
de Boor, Calr, ``CADRE: An Algorithm for Numerical Quadrature,''
  Mathematical Software (John R. Rice, Ed.), New York, Academic Press,
  1971, Chapter 7.

@section GAMALG
 - A Dirac gamma matrix algebra program which takes traces of
and does manipulations on gamma matrices in n dimensions.  It may be
loaded into Maxima by 
LOADFILE("gam");
A preliminary manual is contained in the file SHARE;GAM USAGE and may
be printed using
PRINTFILE(GAM,USAGE,SHARE);