avram/doc/avram.info-2

This is avram.info, produced by makeinfo version 4.13 from
avram.texinfo.

This file documents the `avram' command which is a virtual machine code
interpreter

   Copyright (C) 2000, 2003, 2006-2010, 2012 Dennis Furey Permission is
granted to make and distribute verbatim copies of this manual provided
the copyright notice and this permission notice are preserved on all
copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: avram.info,  Node: Command Line Parsing,  Next: Execution Modes,  Prev: Invocation,  Up: Invocation

3.4.1 Command Line Parsing
--------------------------

A couple of functions declared in `cmdline.h' can be used to do all the
necessary parsing of command lines and environment variables needed by
virtual code applications.

 -- Function: list avm_default_command_line (int ARGC, char *ARGV[],
          int INDEX, char *EXTENSION, char *PATHS, int
          DEFAULT_TO_STDIN_MODE, int FORCE_TEXT_INPUT_MODE, int
          *FILE_ORDINAL)
     The purpose of this function is to build most of the data
     structure used by parameter mode applications, as described in
     *note Input Data Structure::, by parsing the command line
     according to *note Command Line Syntax::. The parameters have
     these interpretations.

    `ARGC'
          is the number elements in the array referenced by `ARGV'

    `ARGV'
          is the address of an array of pointers to null terminated
          character strings holding command line arguments

    `INDEX'
          is the position of the first element of `ARGV' to be
          considered. Those preceding it are ignored.

    `EXTENSION'
          is the address of a string that will be appended to input
          file names given in `ARGV' in an effort to find the
          associated files

    `PATHS'
          is the address of a null terminated character string
          containing a colon separated list of directory names that
          will be searched for input files

    `DEFAULT_TO_STDIN_MODE'
          is set to a non-zero value by the caller if the contents of
          standard input should be read in the absence of input files

    `FORCE_TEXT_INPUT_MODE'
          is set to a non-zero value by the caller to indicate that
          input files should be read as text, using `avm_load' (rather
          than `avm_preamble_and_contents', which would allow them to
          be either text or data). The `PREAMBLE' field of the returned
          file specifications will always be empty when this flag is
          set.

    `FILE_ORDINAL'
          is set to a pointer to an integer by the caller if only one
          file is to be loaded during each call. The value of the
          integer indicates the which one it will be.

     The result returned by this function is a list whose `head' is a
     list of file specifications and whose `tail' is a list of command
     line options intended for input to a virtual code application.

     The list of file specifications returned in the `head' of the
     result follows the same conventions as the `DATA' parameter to the
     function `avm_output_as_directed', except that the `head' of the
     `head' of each item is a list representing the time stamp of the
     file as given by `avm_date_representation'. If the file is
     standard input, then it holds the current system date and time.

     If the `FILE_ORDINAL' parameter is `NULL', then all files on the
     command line are loaded, but if it points to an integer N, then
     only the Nth file is loaded, and N is incremented. If there is no
     Nth file, a `NULL' value is returned as the entire result of the
     function. For a series of calls, the integer should be initialized
     to zero by the caller before the first call.

     If standard input is indicated as one of the files on the command
     line (by a dash), then it is also loaded regardless of the
     `FILE_ORDINAL', but a cached copy of it is used on subsequent
     calls after the first, so that the function does not actually
     attempt to reread it. If standard input is to be loaded, it must
     be finite for this function to work properly.

     The search strategy for files is described in *note Environment::,
     and makes use of the `EXTENSION' and `PATHS' parameters.

     In the list of command line options returned in the `tail' of the
     result, each item is a list with a non-empty `head' and `tail',
     and is interpreted as follows.

        * The `head' of the `head' is a list representing a natural
          number, as given by `avm_natural', indicating the position of
          the option on the command line relative to the initial value
          of the `INDEX' parameter.

        * The `tail' of the `head' is a list which is `NULL' in the
          case of a "short form" option, written with a single dash on
          the command line, but is a list whose `head' and `tail' are
          `NULL' in the case of a "long form" option, written with two
          dashes.

        * The `head' of the `tail' is a list representing a character
          string for the keyword of an option, for example `foo' in the
          case of an option written `--foo=bar,baz'.

        * The `tail' of the `tail' is a list of lists representing
          character strings, with one item for each parameter
          associated with the option, for example, `bar' and `baz'.

     If multiple calls to the function are made with differing values of
     `*FILE_ORDINAL' but other parameters unchanged, the same list of
     options will be returned each time, except insofar as the position
     numbers in the `head' of the `head' of each item are adjusted as
     explained in *note Input for Mapped Applications::.

     Any of the i/o errors or fatal errors associated with other file
     input operations are possible with this function as well. This
     non-fatal warning message is also possible.  

          `PROGRAM-NAME: warning: search paths not supported'

     This error occurs if the library has been built on a platform that doesn't
     have the `argz.h' header file and the `PATHS' parameter is
     non-`NULL'.

 -- Function: list avm_environment (char *ENV[])
     This function takes the address of a null terminated array of
     pointers to null terminated character strings of the form
     `"variable=value"'. The result returned is a list of lists, with
     one item for each element of the array. The `head' of each item is
     a representation of the left side of the corresponding string, and
     the `tail' is a representation of the right.

     This function is therefore useful along with
     `avm_default_command_line' for building the remainder of the data
     structure described in *note Parameter Mode Interface::. For
     example, a virtual machine emulator for non-interactive parameter
     mode applications with no bells and whistles could have the
     following form.

          int
          main(argc,argv,env)
          ...
          {
            FILE *virtual_code_file;
          ...
            avm_initialize_lists();
            avm_initialize_apply();
            avm_initialize_rawio();
            avm_initialize_formout();
            avm_initialize_cmdline();
            virtual_code_file = fopen(argv[1],"rb");
            operator = avm_received_list(
              virtual_code_file,argv[1]);
            fclose(virtual_code_file);
            command = avm_default_command_line(argc,
              argv,2,NULL,NULL,0,0,NULL);
            environs = avm_environment(env);
            operand = avm_join(command,environs);
            result = avm_apply(operator,operand);
            avm_output_as_directed(result,0,0);
            avm_dispose(result);
          ...
          }

     The `avm_environment' function could cause the program to abort due
     to a memory overflow.  For security reasons, it will also abort
     with an error message if any non-printing characters are detected
     in its argument. (See *note Other Diagnostics and Warnings::.)

 -- Function: void avm_initialize_cmdline ()
     This function initializes some local variables and should be called
     before any of the other functions in this section is called, or
     else their results are unpredictable.

 -- Function: void avm_count_cmdline ()
     This function should be called after the last call to any of the
     other functions in this section, as it reclaims some locally
     allocated storage. If the `avm_count_lists' function is used, it
     should be called after this one.


File: avram.info,  Node: Execution Modes,  Prev: Command Line Parsing,  Up: Invocation

3.4.2 Execution Modes
---------------------

Some functions declared in `exmodes.h' are useful for executing
interactive applications or filter mode transducers in a manner
consistent with the specifications described in the previous chapter.

 -- Function: void avm_interact (list AVM_INTERACTOR, int STEP_MODE,
          int ASK_TO_OVERWRITE_MODE, int QUIET_MODE)
     This function executes an interactive virtual code application. The
     parameters have these interpretations.

    `AVM_INTERACTOR'
          is the virtual code for a function that performs as specified
          in *note Output From Interactive Applications::.

    `STEP_MODE'
          will cause all shell commands to be echoed if set to a
          non-zero value, and will cause the program to pause after
          each shell command until a key is pressed.

    `ASK_TO_OVERWRITE_MODE'
          can be set to a non-zero value by the caller to cause the
          program to ask permission of the user to overwrite any
          existing files in cases where the virtual code returns a file
          list as described in *note Mixed Modes of Interaction::.

    `QUIET_MODE'
          can be set to a non-zero value to suppress console messages
          in the case of file output per *note Mixed Modes of
          Interaction::.

     The meaning of this function is accessible to any reader willing
     to slog through *note Output From Interactive Applications::. The
     only subtle point is that `AVM_INTERACTOR' parameter in this
     function does not correspond to the virtual code application that
     `avram' reads from a virtual code file, but to the result computed
     when the application read from the file is applied to the data
     structure representing the command line and environment.

     Any of the memory overflows or i/o errors possible with other
     functions in the library are possible from this one as well, and
     will also cause it to print an error message and halt the program.
     A badly designed virtual code application could cause a deadlock,
     which will not be detected or reported

 -- Function: void avm_trace_interaction ()
     This function enables diagnostic output for the
     `avm_recoverable_interact' function.

 -- Function: void avm_disable_interaction ()
     This function causes `avm_interact' and `avm_recoverable_interact'
     to terminate with an error instead of executing, as required by the
     `--jail' command line option.

 -- Function: list avm_recoverable_interact (list INTERACTOR, int
          *FAULT)
     This function is similar to `avm_interact' but always closes the
     pipe and performs no file i/o, and will return an error message
     rather than exiting. Otherwise it returns a transcript of the
     intereaction as a list of lists of strings represented as lists of
     character encodings.  It implements the INTERACT combinator with
     the virtual code for the transducer function given as the
     parameter.  A prior call to `avm_trace_interaction' will cause
     diagnostic information to be written to standard output when this
     function is executed.

 -- Function: void avm_byte_transduce (list OPERATOR)
     This function executes a filter mode byte transducer application,
     which behaves as described in *note Byte Transducers::. The
     argument is the virtual code for the application, which would be
     found in a virtual code file. There are limited opportunities for
     i/o errors, as only standard input and standard output are
     involved with this function, but fatal errors due to memory
     overflow are possible.

 -- Function: void avm_line_map (list OPERATOR)
     This function executes line mapped filter mode applications, which
     are explained in *note Line Maps::. The argument is the virtual
     code for the application. Similar comments to those above apply.

 -- Function: void avm_initialize_exmodes ()
     This function should be called before any of the other functions
     in this section in order to initialize some local variables.
     Results are undefined if this function isn't called first.

 -- Function: void avm_count_exmodes ()
     This function doesn't do anything in the present version of the
     library, but should be called after the last call to any of the
     other functions in this section in order to maintain compatibility
     with future versions, which may use it for cleaning up local
     variables.


File: avram.info,  Node: Version Management,  Next: Error Reporting,  Prev: Invocation,  Up: Library Reference

3.5 Version Management
======================

The `avram' library is designed to support any number of backward compatibility
modes with itself, by way of some functions declared in `vman.h'. The
assumption is that the library will go through a sequence of revisions
during its life, each being identified by a unique number. In the event
of a fork in the project, each branch will attempt to maintain
compatibility at least with its own ancestors.

 -- Function: void avm_set_version (char *NUMBER)
     This function can be used to delay the demise of a client program
     that uses the library but is not updated very often. The argument
     is a null terminated string representing a version number, such as
     `"0.13.0"'.

     A call to this function requests that all library functions revert
     to their behavior as of that version in any cases where the current
     behavior is incompatible with it. It will also cause virtual code
     applications evaluated with `avm_apply' to detect a version number
     equal to the given one rather than the current one. (See *note
     Version::.)

     The program will exit with an internal error message if any
     function in the library has already interrogated the version
     number before this function is called, or if it is passed a null
     pointer. This problem can be avoided by calling it prior to any of
     the `avm_initialize' functions with a valid address. The program
     will exit with the message

          `PROGRAM-NAME: multiple version specifications'

     if this function is called more than once, even with the same
     number.  If the number is not recognized as a present or past
     version, or is so old that it is no longer supported, the program
     will exit with this message.

          `avram: can't emulate version NUMBER'

     Client programs that are built to last should allow the version
     number to be specified as an option by the user, and let virtual
     code applications that they execute take care of their own backward
     compatibility problems. This strategy will at least guard against
     changes in the virtual machine specification and other changes
     that do not affect the library API.

 -- Function: int avm_prior_to_version (char *NUMBER)
     This function takes the address of a null terminated string
     representing a version number as an argument, such as `"0.13.0"',
     and returns a non-zero value if the version currently being
     emulated predates it.

     If no call has been made to `avm_set_version' prior to the call to
     this function, the current version is assumed, and subsequent
     calls to `avm_set_version' will cause an internal error.

     The intended use for this function would be by a maintainer of the
     library introducing an enhancement that will not be backward
     compatible, who doesn't wish to break existing client programs and
     virtual code applications. For example, if a version `1.0' is
     developed at some time in the distant future, and it incorporates
     a previously unexpected way of doing something, code similar to
     the following could be used to maintain backward compatibility.

          if (avm_prior_to_version("1.0"))
            {
              /* do it the 0.x way */
            }
          else
            {
              /* do it the 1.0-and-later way */
            }

     This function will cause an internal error if the parameter does
     not match any known past or present version number, or if it is a
     null pointer.

 -- Function: char* avm_version ()
     This function returns the number of the version currently being
     emulated as the address of a null terminated string. The string
     whose address is returned should not be modified by the caller.

     If no call has been made to `avm_set_version' prior to the call to
     this function, the current version is assumed, and subsequent
     calls to `avm_set_version' will cause an internal error.


File: avram.info,  Node: Error Reporting,  Next: Profiling,  Prev: Version Management,  Up: Library Reference

3.6 Error Reporting
===================

Most of the error reporting by other functions in the library is done by
way of the functions declared in `error.h'.  These function communicate
directly with the user through standard error.  Client programs should
also use these functions where possible for the sake of a uniform
interface.

 -- Function: void avm_set_program_name (char *ARGV0)
     The argument to this function should be the address of a null
     terminated string holding the name of the program to be reported
     in error messages that begin with a program name. Typically this
     string will be the name of the program as it was invoked on the
     command line, possibly with path components stripped from it. An
     alternative would be to set it to the name of a virtual code
     application being evaluated. If this function is never called, the
     name `"avram"' is used by default. Space for a copy of the program
     name is allocated by this function, and a fatal memory overflow
     error is possible if there is insufficient space available.

 -- Function: char* avm_program_name ()
     This function returns a pointer to a null terminated character
     string holding the program name presently in use. It will be
     either the name most recently set by `avm_set_program_name', or
     the default name `"avram"' if none has been set. The string whose
     address is returned should not be modified by the caller.

 -- Function: void avm_warning (char *MESSAGE)
     This function writes the null terminated string whose address is
     given to standard error, prefaced by the program name and followed
     by a line break.

 -- Function: void avm_error (char *MESSAGE)
     This function writes the null terminated string whose address is
     given to standard error, prefaced by the program name and followed
     by a line break, as `avm_warning', but it then terminates the
     process with an exit code of 1.

 -- Function: void avm_fatal_io_error (char *MESSAGE, char *FILENAME,
          int REASON)
     This function is useful for reporting errors caused in the course
     of reading or writing files. The message is written to standard
     error prefaced by the program name, and incorporating the name of
     the relevant file. The `REASON' should be the error code obtained
     from the standard `errno' variable, which will be translated to an informative
     message if possible by the standard `strerror' function and
     appended to the message. After the message is written, the process
     will terminate with an exit code of 1.

 -- Function: void avm_non_fatal_io_error (char *MESSAGE, char
          *FILENAME, int REASON)
     This function does the same as `avm_fatal_io_error' except that it
     doesn't exit the program, and allows control to return to the
     caller, which should take appropriate action.

 -- Function: void avm_internal_error (int CODE)
     This function is used to report internal errors and halt the
     program. The error message is written to standard error prefaced
     by the program name and followed by a line break. The code should
     be a unique integer constant (i.e., not one that's used for any
     other internal error), that will be printed as part of the error
     message as an aid to the maintainer.

     This function should be used by client programs only in the event
     of conditions that constitute some violation of a required
     invariant. It indicates to the user that something has gone wrong
     with the program, for which a bug report would be appropriate.

 -- Function: void avm_reclamation_failure (char *ENTITY, counter COUNT)
     This function is used only by the `avm_count' functions to report
     unreclaimed storage. The `COUNT' is the number of units of storage
     left unreclaimed, and the `ENTITY' is the address of a null
     terminated string describing the type of unreclaimed entity, such
     as `"lists"' or `"branches"'. The message is written to standard
     error followed by a line break, but the program is not halted and
     control returns to the caller.


File: avram.info,  Node: Profiling,  Next: Emulation Primitives,  Prev: Error Reporting,  Up: Library Reference

3.7 Profiling
=============

The functions declared in `profile.h' can be used for constructing and
writing tables of run time statistics such as those mentioned in *note
Files::, and *note Profile::. These functions maintain a database of
structures, each recording the statistics for a particular virtual code
fragment.

   Each structure in the database is identified by a unique key, which
must be a list representing a character string. A pointer to such a
structure is declared to be of type `score'. For the most part, the data
structure should be regarded as opaque by a client program, except for a
field `reductions' of type `counter', which may be modified arbitrarily
by the client.

   The way these operations are used in the course of evaluating virtual
code applications containing profile annotations is to add a structure
to the database each time a new profiled code fragment is encountered,
using the annotation as its key, and to increment the `reductions' of
the structure each time any constituent of the code gets a quantum of
work done on it. Other ways of using these operations are left to the
developer's discretion.

 -- Function: score avm_entries (list TEAM, list *MESSAGE, int *FAULT)
     This function retrieves or creates a data base entry given its
     key. The parameters have these interpretations.

    `TEAM'
          is a list representing a character string that uniquely
          identifies the database entry to be retrieved or created.

    `MESSAGE'
          is the address of a list known to the caller, which will be
          assigned a list representing an error message if any error
          occurs in the course of searching the database or creating a
          new entry.

    `FAULT'
          is the address of an integer that will be set to a non-zero
          value if any error is caused by this function.

     The pointer returned by this function is the address of the record
     whose key is given by the `TEAM' parameter. If such a record is
     already in the database, its address is returned, but otherwise a
     new one is created whose address is then returned. The `reductions'
     field of a newly created entry will be zero.

     In the course of searching the database, the `avm_compare'
     function is used, so the associated lists may be modified as noted
     in *note Comparison::.  It is not necessary for a client to
     include the header file `compare.h' or to call
     `avm_initialize_compare' in order to use the profile operations,
     because they are done automatically.

     If an error message is assigned to the list referenced by
     `MESSAGE', the integer referenced by `FAULT' will be set to a
     non-zero value. The form of the error message will be a list in
     which each item is a list of character representations as per
     *note Character Table::. It is the responsibility of the caller to
     dispose of the error message. Currently the only possible error is
     a memory overflow, which in this case is non-fatal.

 -- Function: void avm_tally (char *FILENAME)
     This function makes a table of the results stored in the data base
     built by the `avm_entries' function. The argument is the address
     of a null terminated character string containing the name of the
     file in which the results will be written. A file is opened and
     the table is written in a self explanatory text format, with
     columns labeled "reductions" and "invocations" among others. The
     latter contains the number of times the associated key was
     accessed through `avm_entries'.

     The data written to the file should be taken with a grain of salt.
     It is computed using native integer and floating point arithmetic,
     with no checks made for overflow or roundoff error, and no
     guarantee of cross platform portability. The number of
     "reductions" means whatever the developer of the client program
     wants it to mean.

     The following error messages are possible with this function,
     which will be written to standard error. None of them is fatal.  

        * `PROGRAM-NAME: can't write FILENAME'

        * `PROGRAM-NAME: can't write to FILENAME'

        * `PROGRAM-NAME: can't close FILENAME'

        * `PROGRAM-NAME: invalid profile identifier'

     The last message is reported if any record in the database has a
     key that is not a list of valid character representations. The
     others are accompanied by an explanation from the standard
     `strerror' function if possible.

 -- Function: void avm_initialize_profile ()
     This function should be called before any of the other functions
     in this section in order to initialize the data base. Results are
     undefined if it is not called first.

 -- Function: void avm_count_profile ()
     This function can be called after the other functions in this
     section as a way of detecting memory leaks. If any storage remains
     unreclaimed that was created by the functions in this section, a
     warning message is written to standard error. If the
     `avm_count_lists' function is being used by the client program, it
     should be called after this one.


File: avram.info,  Node: Emulation Primitives,  Next: External Library Maintenance,  Prev: Profiling,  Up: Library Reference

3.8 Emulation Primitives
========================

The functions documented in this section can be used to take very
specific control over the evaluation of virtual code applications. It is
unlikely that a client program will have any need for them unless it
aims to replace or extend the `avm_apply' function.

   The virtual machine is somewhat removed from a conventional von
Neumann model of computation, so emulating it in C or any other
imperative language is less straightforward than one would prefer. An
elaborate system of interdependent data structures is used to represent
partially evaluated computations, which does not particularly lend
itself to a convenient, modular API. The abstraction provided by the
functions in this section is limited mainly to that of simple memory
management and stack operations. Consequently, a developer wishing to
build on them effectively would need to _grok_ the data structures
involved, which are described in some detail.

* Menu:

* Lists of Pairs of Ports::
* Ports and Packets::
* Instruction Stacks::


File: avram.info,  Node: Lists of Pairs of Ports,  Next: Ports and Packets,  Prev: Emulation Primitives,  Up: Emulation Primitives

3.8.1 Lists of Pairs of Ports
-----------------------------

A `port' is the name given to a type of pointer used in the library as
the address of a place where a computational result yet to be evaluated
will be sent. Ports are discussed further in *note Ports and Packets::,
but are mentioned here because it is sometimes necessary to employ a
list of pairs of them. A pointer to such a list is declared as a
`portal' type. It refers to a structure of the form 

     struct port_pair
     {
       port left;
       port right;
       portal alters;
     }

   A small selection of functions for `portal' memory management is
declared as follows in the header file `portals.h'. For reasons of
C-ness, the type declarations themselves are forced to be in `lists.h'.

 -- Function: portal avm_new_portal (portal ALTERS)
     This function is used to create storage for a new `port_pair'
     structure, and returns a `portal' pointer to it if successful. If
     the storage can't be allocated, a `NULL' pointer is returned.  The
     `alters' field of the result is initialized as the given parameter
     supplied by the caller. All other fields are filled with zeros.

 -- Function: void avm_seal (portal FATE)
     This function performs the reclamation of storage associated with
     `portal' pointers, either by freeing them or by consigning them
     temporarily to a local cache for performance reasons. Client
     programs should use only this function for disposing of `portal'
     storage rather than using `free' directly, so as to allow accurate
     record keeping.

 -- Function: void avm_initialize_portals ()
     This function should be called by a client program prior to calling
     either of the above memory management functions in order to
     initialize some local variables. Anomalous results are possible
     otherwise.

 -- Function: void avm_count_portals ()
     This function should be called at the end of a run or after the
     last call to any of the other functions in this section as a way
     of detecting memory leaks associated with `portal' pointers. A
     warning message will be written to standard error if any remains
     unreclaimed.


File: avram.info,  Node: Ports and Packets,  Next: Instruction Stacks,  Prev: Lists of Pairs of Ports,  Up: Emulation Primitives

3.8.2 Ports and Packets
-----------------------

A pointer type declared as a `port' points to a structure in the
following form, where a `flag' is an unsigned short integer type, and a
`counter' is an unsigned long integer.  

     struct avm_packet
     {
       port parent;
       counter errors;
       portal descendents;
       list impetus, contents;
       flag predicating;
     };

For reasons that make sense to C, the `avm_packet' and `port' types are
declared in `lists.h', but a few memory management operations on them
are available by way of functions declared in `ports.h'. The intended
meaning of this structure is described presently, but first the memory
management functions are as follows.

 -- Function: port avm_newport (counter ERRORS, port PARENT, int
          PREDICATING)
     This function attempts to allocate storage for a new packet
     structure and returns its address if successful. If storage can
     not be allocated, a `NULL' pointer is returned. The `errors',
     `parent', and `predicating' fields are initialized with the
     parameters supplied by the caller. The rest of the structure is
     filled with zeros. A local memory cache is used for improved
     performance.

 -- Function: void avm_sever (port APPENDAGE)
     This function reclaims the storage associated with a `port', either
     freeing it entirely or holding it in a local cache.  None of the
     entities that may be referenced by pointers within the structure
     are affected.  Only this function should be used by client
     programs for disposing of ports, not the `free' function directly,
     or some internal bookkeeping will be disrupted. An internal error
     results if the argument is a `NULL' pointer.

 -- Function: void avm_initialize_ports ()
     This function must be called prior to calling either of the two
     above, in order to initialize some static variables.

 -- Function: void avm_count_ports ()
     This function may be called after the last call to any of the other
     functions in this section in order to detect and report unreclaimed
     storage associated with ports. A non-fatal warning will be written
     to standard error if any is detected, but otherwise there is no
     effect.

   The interesting aspect of this data structure is the role it plays in
capturing the state of a computation. For this purpose, it corresponds
to a single node in a partially computed result to be represented by a
`list' when it's finished. The nodes should be envisioned as a
doubly-linked binary tree, except that the pair of `descendents' for
each node is not yet known with certainty, so a list of alternatives
must be maintained.

   Because the computation is not completed while this data structure
exists, there are always some empty fields in it. For example, the
`descendents' and the `contents' fields embody the same information,
the latter doing so in a compact as opposed to a more expanded form.
Hence, it would be redundant for both fields to be non-empty at the
same time. The data structure is built initially with `descendents' and
no `contents', only to be transformed into one with `contents' and no
`descendents'.

   The significance of each field in the structure can be summarized as
follows.

`contents'
     If the computational result destined for the `port' pointing to
     this packet is not complete, then this field is `NULL' and the
     `descendents' are being computed. Otherwise, it contains the result
     of the computation.

`descendents'
     This field points to a list of pairs of ports serving as the
     destinations for an ensemble of concurrent computations.(1) The
     `head' and `tail' of the `contents' are to be identified
     respectively with the `contents' of the `left' and `right' `port'
     in the first pair to finish being computed.

`parent'
     If this packet is addressed by the `left' or the `right' of `port'
     in one of the `descendents' of some other packet, then this field
     points to that packet.

`errors'
     A non-zero value in this field indicates that the result destined
     for the `contents' of this packet is expected to be an error
     message. If the exact level of error severity incurred in the
     computation of the `contents' matches this number, then the
     contents can be assigned the result, but otherwise the result
     should propagate to the `contents' of the `parent'.

`predicating'
     A non-zero value in this field implies that the result destined
     for the `contents' of this packet is being computed in order to
     decide which arm of a conditional function should be chosen. I.e.,
     a `NULL' result calls for the one that is invoked when the
     predicate is false.

`impetus'
     If the result destined for the `contents' of this packet is being
     computed in order to transform a virtual code fragment from its
     original form to an equivalent representation capable of being
     evaluated more directly, this field points to a `list' node at the
     root of the virtual code in its original form.

   One of the hitherto undocumented fields in a `list' node structure declared
in `lists.h' is called the `interpretation', and is of type `list'. A
client program delving into sufficient depth of detail to be concerned
with ports and packets may reasonably assign the `interpretation' field
of the `list' referenced by the `impetus' field in a packet to be a
copy of the `contents' of the packet when they are eventually obtained.
Doing so will save some time by eliminating the need for it to be
recomputed if the same virtual code should be executed again.

   If this course is taken, the `facilitator' field in a `list' node,
also hitherto undocumented, should contain the address of the packet
referring to the list node as its `impetus'. The reason for this
additional link is so that it can be followed when the `impetus' of the
packet is be cleared by `avm_dispose' in the event that the `list' node
is freed before the computation completes. This action is performed in
order to preclude a dangling pointer in the `impetus' field.

   ---------- Footnotes ----------

   (1) Earlier versions of `avram' included a bottom avoiding choice
combinator that required this feature, but which has been withdrawn. A
single pair of descendent ports would now suffice.


File: avram.info,  Node: Instruction Stacks,  Prev: Ports and Packets,  Up: Emulation Primitives

3.8.3 Instruction Stacks
------------------------

A header file named `instruct.h' declares a number of memory management
and stack operations on a data structure of the following form.  

     struct instruction_node
     {
       port client;
       score sheet;
       struct avm_packet actor;
       struct avm_packet datum;
       instruction dependents;
     };

   In this structure, an `instruction' is a pointer to an
`instruction_node', a `score' is a pointer to a profile database entry
as discussed in *note Profiling::, and the `port' and `avm_packet'
types are as described in *note Ports and Packets::.

   This data structure is appropriate for a simple virtual machine code evaluation
strategy involving no concurrency. The strategy to evaluate an
expression `F X' would be based on a stack of these nodes threaded
through the `dependents' field, and would proceed something like this.

  1. The stack is initialized to contain a single node having `F' in
     its `actor.contents' field, and `X' in its `datum.contents' field.

  2. The `client' in this node would refer to a static packet to whose
     `contents' field the final result will be delivered.

  3. The evaluator examines the `actor.contents' field on the top of the
     stack, detects by its form the operation it represents, and decides
     whether it corresponds to one that can be evaluated immediately by
     way of a canned function available in the library. List reversal,
     transposition, and comparison would be examples of such operations.

  4. If the operation can be performed in this way, the result is
     computed and assigned to the destination indicated by the `client'
     field.

  5. If the operation is not easy enough to perform immediately but is
     of a form recognizable as a combination of simpler operations, it
     is decomposed into the simpler operations, and each of them is
     strategically positioned on the stack so as to effect the
     evaluation of the combination. For example, if `F' were of the form
     `compose(G,H)' (`silly' notation), the node with `F' and `X' would
     be popped, but a node with `G' as its `actor.contents' would be
     pushed, and then a node with `H' as its `actor.contents' and `X'
     as its `datum.contents' would be pushed. Furthermore, the `client'
     field of the latter node would point to the `datum.contents' of
     the one with `G', and the `client' field of the one with `G' would
     point wherever the `client' of the popped node used to point.

  6. If the operation indicated by the top `actor.contents' is neither
     implemented by a canned operation in the library nor easily
     decomposable into some that are, the evaluator can either give up
     or use virtual code to execute other virtual code. The latter
     trick is accomplished by pushing a node with `F' as its
     `datum.contents', and a copy of a hard coded virtual code
     interpreter `V' as its `actor.contents'. The `client' of this node
     will point to the `F' in the original node so as to overwrite it
     when a simplified version is subsequently computed. The
     implementation of `V' is a straightforward exercise in `silly'
     programming.

  7. In any case, the evaluator would continue working on the stack
     until everything on it has been popped, at which time the result
     of the entire computation will be found in the packet addressed by
     the `client' in the original instruction node.

   What makes this strategy feasible to implement is the assumption of a
sequential language, wherein synchronization incurs no cost and is
automatic. The availability of any operand is implied by its position at
the top of the stack. If you are reading this section with a view to implementing
a concurrent or multi-threaded evaluation strategy, it will be apparent
that further provisions would need to be made, such as that of a
`data_ready' flag added to the `avm_packet' structure.

   The following functions support the use of stacks of instruction
nodes that would be needed in an evaluation strategy such as the one
above.

 -- Function: int avm_scheduled (list ACTOR_CONTENTS, counter
          DATUM_ERRORS, list DATUM_CONTENTS, port CLIENT, instruction
          *NEXT, score SHEET)
     This function performs the memory allocation for instruction
     nodes. It attempts to create one and to initialize the fields with
     the given parameters, returning a pointer to it if successful. It
     returns a `NULL' pointer if the storage could not be allocated.

     Copies of the `list' parameters `actor_contents' and
     `data_contents' are made by this function using `avm_copied', so
     the originals still exist as far as the caller is concerned and
     will have to be deallocated separately from this structure. The
     copies are made only if the allocation succeeds.

     Any fields other than those indicated by the parameters to this
     function are filled with zeros in the result.

 -- Function: void avm_retire (instruction *DONE)
     This function performs the storage reclamation of instructions,
     taking as its argument the instruction to be reclaimed. The `list'
     fields in the structure corresponding to the `list' parameters
     used when it was created are specifically reclaimed as well, using
     `avm_dispose'.

     The argument to this function is the address of an `instruction'
     rather than just an `instruction' so that the `instruction' whose
     address is given may be reassigned as the `dependents' field of
     the deallocated node. In this way, the instructions can form a
     stack that is popped by this function.

     This function cooperates with `avm_scheduled' in the use of a local
     cache of instruction nodes in the interest of better performance.
     Client modules should not attempt to allocate or reclaim
     instructions directly with `malloc' or `free', but use only these
     functions.

     It causes a fatal internal error to pass a `NULL' pointer to this
     function.

 -- Function: void avm_reschedule (instruction *NEXT)
     Given the address of an instruction pointer that may be regarded
     as the top of a stack of instructions threaded through the
     `dependents' field, this function exchanges the positions of the
     top instruction and the one below it. A fatal internal error is
     caused if there are fewer than two instructions in the stack.

     A use for this function arises in the course of evaluating virtual
     code applications of the form `conditional(P,(F,G))' (in `silly'
     notation). The evaluation strategy would require pushing nodes for
     all three constituents, but with `P' pushed last (therefore
     evaluated first). The result of the evaluation of `P' would
     require either the top one or the one below it to be popped
     without being evaluated, depending on whether the result is empty.

 -- Function: void avm_initialize_instruct ()
     This function should be called before any of the instruction memory
     management functions is called in order to initialize some local
     data structures. Results are unpredictable without it.

 -- Function: void avm_count_instruct ()
     This function should be called after the last call to any of the
     other functions in this section in order to detect and report
     unreclaimed storage associated with them. A warning message will be
     written to standard error if any unreclaimed instructions remain.
     This function relies on the assumption that the memory management
     has been done only by way of the above functions.


File: avram.info,  Node: External Library Maintenance,  Prev: Emulation Primitives,  Up: Library Reference

3.9 External Library Maintenance
================================

External mathematical library functions such as those documented in
*note External Libraries:: that are invoked from virtual code by the
`library' combinator (*note Library combinator::) are also accessible
from C by way of a uniform API implemented by the functions declared in
`libfuns.h'. This interface applies even to libraries implemented in
Fortran such as `minpack'. This section briefly documents the functions
in `libfuns.h' and sets out some recommeded guidelines for developers
wishing to add support for other external libraries.

* Menu:

* Calling existing library functions::
* Implementing new library functions::
* Working around library misfeatures::


File: avram.info,  Node: Calling existing library functions,  Next: Implementing new library functions,  Prev: External Library Maintenance,  Up: External Library Maintenance

3.9.1 Calling existing library functions
----------------------------------------

Whatever data types a library function manipulates, its argument and
its result are each ultimately encoded each by a single list as
explained in *note Type Conversions::. This representation allows all
library functions to be invoked by a uniform calling convention as
detailed below.

 -- Function: list avm_library_call (list LIBRARY_NAME, LIST
          FUNCTION_NAME, list ARGUMENT, int *FAULT)
     This function serves as an interpreter of external library
     functions by taking a LIBRARY_NAME, a FUNCTION_NAME, and an
     ARGUMENT to the result returned by the corresponding library
     function for the given ARGUMENT.

     The library and function names should be encoded as lists of
     character representations, the same as the arguments that would be
     used with the `library' combinator if it were being invoked by
     virtual code (with attention to the backward compatibility issue
     explained in *note Characters and Strings::).

     If an error occurs in the course of evaluating a library function,
     the integer referenced by FAULT will be assigned a non-zero value,
     and the result will be a list of character string representations
     explaining the error, such as `<'memory overflow'>', for example.
     Otherwise, the list returned will encode the result of the library
     function in a way that depends on the particular function being
     evaluated.

 -- Function: list avm_have_library_call (list LIBRARY_NAME, list
          FUNCTION_NAME, int *FAULT)
     This function implements the `have' combinator described in *note
     Have combinator::, which tests for the availability of a library
     function. The LIBRARY_NAME and FUNCTION_NAME parameters are as
     explained above for `avm_library_call', and `fault' could signal
     an error similarly for this function as well.

     The result returned will be an error message in the event of an
     error, or a list of pairs of strings otherwise. The list will be
     empty if the library function is not available. If the library
     function is available, the list will contain a single pair, as in

          <(library_name,function_name)>

     In addition, the list representation of the character string `'*''
     can be specified as either the library name or the function name
     or both. This string is interpreted as a wild card and will cause
     all matching pairs of library and function names to be returned in
     the list.

 -- Function: void avm_initialize_libfuns ()
     This function initializes some static data structures used by the
     two functions above. It may be called optionally before the first
     call to either of them, but will be called automatically if not.

 -- Function: void avm_count_libfuns ()
     This function can be used as an aid to detecting memory leaks. It
     reclaims any data structures allocated by `avm_initialize_libfuns'
     and should be called towards the end of a run some time prior to
     `avm_count_lists' *note Simple Operations::, if the latter is
     being used.


File: avram.info,  Node: Implementing new library functions,  Next: Working around library misfeatures,  Prev: Calling existing library functions,  Up: External Library Maintenance

3.9.2 Implementing new library functions
----------------------------------------

Adding more external libraries to `avram' is currently a manual
procedure requiring the attention of a developer conversant with C.  To
support a new library called `foobar', these steps need to be followed
at a minimum.

   * Create a new file called `foobar.h' under the `avm/' directory in
     the main source tree whose name doesn't clash with any existing
     file names and preferably doesn't induce any proper prefixes among
     them. This file should contain at least these function
     declarations.

          extern list avm_foobar_call (list function_name,list argument,
                                       int *fault);

          extern list avm_have_foobar_call (list function_name,int *fault);

          extern void avm_initialize_foobar ();

          extern void avm_count_foobar ();

     There should also be the usual preprocessor directives for
     `include' files. The naming convention shown should be followed in
     anticipation of automated support for these operations in the
     future.

   * Add `foobar.h' to the list of other header files in
     `avm/Makefile.am'.

   * Create a new file called `foobar.c' under the `src/' directory
     whose name doesn't clash with any existing file names to store
     most of the library interface code. It can start out with stubs
     for the functions declared in `foobar.h'.

   * Add `foobar.c' to the list of other source files in
     `src/Makefile.am'

   * Execute the following command in the main `avram-x.x.x' source
     directory where the file `configure.in' is found.

          aclocal \
          && automake --gnu --add-missing \
          && autoconf

     This command requires having `automake' and `autoconf' installed
     on your system.

   * Make the following changes to `libfuns.c'.

        * Add the line `#include<avm/foobar.h>' after the other
          `include' directives.

        * Add the string `"foobar"' to the end of the array of
          `libnames' in `avm_initialize_libfuns'.

        * Add a call to `avm_initialize_foobar' to the body.

        * Add a call to `avm_count_foobar' to the body of
          `avm_count_libfuns'.

        * Add a case of the form
               case nn:
                 return avm_foobar_call(function_name,argument,fault);

          after the last case in `avm_library_call', being careful not
          to change the order, and using the same name as above in the
          file `foobar.h'.

        * Add a case of the form
               case nn:
                 looked_up = avm_have_foobar_call(function_name,fault);
                 break;

          after the last case in `avm_have_library_call', being careful
          not to change the order, and using the same name as above in
          the file `foobar.h'.

   * Edit `foobar.c' and `foobar.h' to suit, periodically compiling and
     testing by executing `make'.

   * Package and install at will.

   The functions shown above have the obvious interpretations, namely
that `avm_foobar_call' evaluates a library function from the `foobar'
library, and `avm_have_foobar_call' tests for a function's
availability. The latter should interpret wild cards as explained in
*note Calling existing library functions::, but should return only a
list of strings for the matching function names rather than a list of
pairs of strings, as the library name is redundant.  The remaining
functions are for static initialization and reclamation.

   These functions should consist mainly of boilerplate code similar to
the corresponding functions in any of the other library source files,
which should be consulted as examples. The real work would be done by
other functions called by them. These should be statically declared
within the `.c' source file and normally not listed in the `.h' header
file unless there is some reason to think they may be of more general
use. Any externally visible functions should have names beginning with
`avm_' to avoid name clashes.

   Some helpful hints are reported below for what they may be worth.

   * The reason for doing this is to leverage off other people's
     intelligence, so generally `foobar.c' should contain only glue
     code for library routines developed elsewhere with great skill
     rather than reinventing them in some home grown way.

   * The best numerical software is often written by Fortran programmers.
     Linking to a Fortran library is no problem on GNU systems provided
     that all variables are passed by reference and all arrays are
     converted to column order (*note Type Conversions::).

   * Most C++ programmers have yet to reach a comparable standard, but
     C++ libraries can also be linked by running `nm' on the static library
     file to find out the real names of the functions and `c++filt' to
     find out which is which. However, there is no obvious workaround
     for the use of so called derived classes by C++ programmers to
     simulate passing functions as parameters.

   * Anything worth using can probably be found in the Debian archive.

   * Not all libraries are sensible candidates for interfaces to
     `avram'. Typical design flaws are

        * irrepressible debugging messages written to `stderr' or
          `stdout' that are unfit for end user consumption

        * deliberately crashing the application if `malloc' fails

        * opaque data types with undocumented storage requirements

        * opaque data types that would be useful to store persistently
          but have platform specific binary representations

        * heavily state dependent semantics

        * identifiers with clashing names

        * restrictive licenses

     Some of these misfeatures have workarounds as explained next in
     *note Working around library misfeatures::, at least if there's
     nothing else wrong with the library.

   Those who support `avram' are always prepared to assist in the
dissemination of worthwhile contributed library modules under terms
compatible with *note Copying::, and under separate copyrights if preferred.
Contributed modules can be integrated into the official source tree
provided that they meet the following additional guidelines to those
above.

   * source code documentation and indentation according to GNU coding
     standards (`http://www.gnu.org/prep/standards')

   * sufficient stability for a semi-annual release cycle

   * no run-time or compile-time dependence on any non-free software,
     although dynamic loading and client/server interaction are
     acceptable

   * portable or at least unbreakable configuration by appropriate use
     of `autoconf' macros and conditional defines

   * little or no state dependence at the level of the virtual code interface
     (i.e., pure functions or something like them, except for random
     number generators and related applications)

   * adequate documentation for a section in *note External Libraries::


File: avram.info,  Node: Working around library misfeatures,  Prev: Implementing new library functions,  Up: External Library Maintenance

3.9.3 Working around library misfeatures
----------------------------------------

As mentioned already (*note Implementing new library functions::), some
common problems with external libraries that are worthwhile in other
respects are that they may generate unwelcome console output while
running, they may follow ill defined memory management policies, and
they may handle exceptions just by crashing themselves along with the
client module.

   An accumulation of techniques for coping with these issues (short of
modifying the library source) has been collected into the API and made
available by way of the header file `mwrap.h'. This section briefly
documents how they might be put to use.

* Menu:

* Inept excess verbiage::
* Memory leaks::
* Suicidal exception handling::


File: avram.info,  Node: Inept excess verbiage,  Next: Memory leaks,  Prev: Working around library misfeatures,  Up: Working around library misfeatures

3.9.3.1 Inept excess verbiage
.............................

Although the author of a library function may take pride in putting its
activities on display, it should be assumed that virtual code
applications running on `avram' have other agendas for the console, so
the library interface module should prevent direct output from the
external library.

   More thoughtful API's may have a verbosity setting, which should be used
in preference to this workaround, but failing that, it is easy to
dispense with console output generated by calls to external library
functions by using some combination of the following functions.

 -- Function: void avm_turn_off_stdout ()
     Calling this function will suppress all output to the standard
     output stream until the next time `avm_turn_on_stdout' is called.
     Additional calls to this function without intervening calls to
     `avm_turn_on_stdout' may be made safely with no effect.  The
     standard output stream is flushed as a side effect of calling this
     function.

 -- Function: void avm_turn_on_stdout ()
     Calling this function will allow output to the standard output
     stream to resume if it has been suppressed previously by a call to
     `avm_turn_off_stdout'. If `avm_turn_off_stdout' has not been
     previously called, this function has no effect. Any output that
     would have been sent to `stdout' during the time it was turned off
     will be lost.

 -- Function: void avm_turn_off_stderr ()
     This function performs a similar service to that of
     `avm_turn_off_stdout' but pertains to the standard error stream.
     The standard error and the standard output streams are controlled
     independently even if both of them are piped to the same console.

 -- Function: void avm_turn_on_stderr ()
     This function performs a similar service to that of
     `avm_turn_on_stdout' but pertains to the standard error stream.

   As an example, the following code fragment will prevent any output to
standard output taking place as a side effect of `blather', but will
allow error messages to standard error. Note that ouput should not be
left permanently turned off.

     ...
     #include <avm/mwrap.h>
     ...

     x = y + z;
     avm_turn_off_stdout ();
     w = blather (foo, bar, baz);
     avm_turn_on_stdout ();
     return w;
     ...

   One possible issue with these functions is that they rely on a
feature of the GNU C library that might not be portable to non-GNU systems
and has not been widely tested on other platforms.

   Another issue is that a library function could be both careless
enough to clutter the console unconditionally and meticulous enough to
check for I/O errors after each attempted write. Writing while the
output stream is disabled will return an I/O error to the caller (i.e.,
to the verbose library function) for appropriate action, which could
include terminating the process.


File: avram.info,  Node: Memory leaks,  Next: Suicidal exception handling,  Prev: Inept excess verbiage,  Up: Working around library misfeatures

3.9.3.2 Memory leaks
....................

Incorrect memory management may undermine confidence in a library when
one wonders what else it gets wrong, but if the worst it does is leave
a few bytes unreclaimed, then help is at hand.

   The first priority is to assess the seriousness of the situation.
Similarly to the way library functions are bracketed with calls to
those listed in *note Inept excess verbiage::, the following functions
are meant to be placed before and after a call to a library function
either for diagnostic purposes or production use.

 -- Function: void avm_manage_memory ()
     After this function is called, all subsequent calls to the
     standard C functions `malloc', `free', and `realloc' are
     intercepted and logged until the next time
     `avm_dont_manage_memory' is called. Furthermore, a complete record
     is maintained of the addresses and sizes of all allocated areas of
     memory during this time in a persistent data structure managed
     internally.

 -- Function: void avm_dont_manage_memory ()
     Calling this function suspends the storage monitoring activities
     initiated by calling `avm_manage_memory', but the record of
     allocated memory areas is not erased.

 -- Function: void avm_debug_memory ()
     After this function is called and `avm_manage_memory' is also
     called, the standard output stream will display a running account
     of the sizes and addresses of all memory allocations or
     deallocations as they occur until the next call to either
     `avm_dont_debug_memory' or `avm_dont_manage_memory'.

 -- Function: void avm_dont_debug_memory ()
     This function stops the output being sent to `stdout' caused by
     `avm_debug_memory', if any, but has no effect on the logging of
     memory management events preformed due to `avm_manage_memory'.

   While the latter two are not useful in production code, they can help
to clarify an inadequately documented API during development by
experimentally identifying the functions that cause memory to be
allocated. They can also provide the answer to questions like whether
separate copies are made from arrays passed to functions (useful for
knowing when it's appropriate to free them).

   Although the console output reveals everything there is to know about
memory management during the selected window, the question of
unreclaimed storage is more directly settled by the following functions.

 -- Function: void avm_initialize_mwrap ()
     This function has to be called before any other functions from
     `mwrap.h' in order to clean the slate and prepare the static data
     structures for use. This function might not have to be called
     explicitly if the client module is part of `avram', whose main
     program would have already called it. There is no harm in calling
     it repeatedly.

 -- Function: void avm_count_mwrap ()
     This function should be called after the last call to any other
     functions in `mwrap.h', when it is expected that all storage that
     was allocated while `avm_manage_memory' was in effect should have
     been reclaimed.

     If there is no unreclaimed storage allocated during an interval
     when memory was being managed, this function returns uneventfully.
     However, if any storage remains unreclaimed, a message stating the
     number of bytes is written to `stderr'.

     If `avm_debug_memory' is also in effect when this function detects
     unreclaimed storage, an itemized list of the unreclaimed memory
     addresses and their sizes is written to standard output.

   Of course, in order for `avm_count_mwrap' to report meaningful
results, any memory that is allocated during the interval between calls
to `avm_manage_memory' and `avm_dont_manage_memory' must have been
given an opportunity to be reclaimed also while this logging mechanism
is in effect. However, there may be arbitrarily many intervening
intervals during which it is suspended.

   On the other hand, any storage that is allocated when memory is not
being managed must not be freed at a time when it is (except for
freeing a `NULL' pointer, which is tolerated but not encouraged). Doing
so raises an internal error, causing termination with extreme
prejudice. This behavior is a precaution against library functions
freeing storage that they didn't allocate, which would mean no memory
is safe and it's better for `avram' not to continue.

   If these investigations uncover no evidence of a memory leak, then
perhaps the relevant library functions are reliable enough to run
without supervisory memory management. Alternatively, when memory leaks
are indicated, the next function provides a simple remedy.

 -- Function: void avm_free_managed_memory ()
     This function causes all storage to be reclaimed that was allocated
     at any time while logging of memory allocation was in effect (i.e.,
     whenever `avm_manage_memory' had been called more recently than
     `avm_dont_manage_memory'). When the storage is freed, no further
     record of it is maintained.

     A side effect of this function is to call `avm_dont_manage_memory'
     and therefore leave memory management turned off.

   This last function when used in conjunction with the others is
therefore the workaround for library functions that don't clean up
after themselves. It may be important to do it for them if repeated
calls to the library function are expected, which would otherwise cause
unreclaimed storage to accumulate until it curtailed other operations.

   One small issue with this function is the assumption that unreclaimed
storage is really a leak and not internal library data that is designed
to persist between calls. If this assumption is not valid, breakage
will occur. However, libraries deliberately making use of persistent
data are likely to have initialization and destructor functions as part
of their API's, so this assumption is often justified if they don't.

   An example of using these functions is given below.

   In this example, `allocated_library_object' is a hypothetical
function exported by an external library that causes storage to be
allocated, and `library_reclamation_routine' is provided by the same
library ostensibly to reclaim the storage thus allocated. However, the
latter is suspected of memory leaks.

   The variable `my_data' is declared and used by an `avram' developer
who is presumably competent to reclaim it correctly, rather than it
being part of an external library. Memory management is therefore
enabled during the calls to the library routines but not at other times.

   The call to `avm_count_mwrap' is redundant immediately after a call
to `avm_free_managed_memory', because with all managed memory having
been freed, no memory leak will ever be detected, but it is included
for illustrative purposes.

     #include <avm/mwrap.h>
     ...

     {
       void *behemoth;
       char *my_data;

       avm_initialize_mwrap ();
       avm_manage_memory ();
       behemoth = allocated_library_object (foo, bar);
       avm_dont_manage_memory ();
       my_data = (char *) malloc (100);
       ...
       free (my_data);
       avm_manage_memory ();
       library_reclamation_routine (&behemoth);
       avm_free_managed_memory ();
       avm_count_mwrap ();
       return;
     }

   It might be a cleaner solution in some sense to omit the call to
`library_reclamation_routine' entirely, because the storage allocated
during the call to `allocated_library_object' will be reclaimed
perfectly well by `avm_free_managed_memory' without it. Doing so may
also be the only option if the library reclamation routine is either
extremely unreliable or non-existent. However, the style above is to be
preferred for portability if possible. The memory management functions
rely on the availability of the system header file `malloc.h', and GNU
C library features whose portability is not assured.  If the required
features are not detected on the host system at configuration time,
conditional directives in the `avram' source will make the `avm_'*
memory management functions perform no operations, and the
responsibility for memory management will devolve to the possibly less
robust external library implementation.


File: avram.info,  Node: Suicidal exception handling,  Prev: Memory leaks,  Up: Working around library misfeatures

3.9.3.3 Suicidal exception handling
...................................

An inconvenient characteristic of some external library functions is to
terminate the program rather than returning an error status to the
caller for routine events such as a failure of memory allocation.
Although in many cases there is no simple workaround for this behavior,
memory allocation failures at least can be detected and preventive
action taken by using the functions described in this section.

   The general approach is to use memory management functions from
`mwrap.h' as described previously (*note Memory leaks::), while
additionally registering a return destination for a non-local jump to be
taken in the event of a memory overflow. The jump is taken when an
external library function calls `malloc' or `realloc' unsuccessfully.
The jump avoids passing control back to the library function, thereby
denying it the opportunity to abort, but restores the context to that
of the jump destination almost as if the library function and all of
its intervening callers had returned normally.

   The interface is similar to that of the standard `setjmp' function
defined in the system header file `setjmp.h', and in fact is built on
it, but differs in that the client module does not explicitly refer to
jump buffers. Instead, the `mwrap' module internally maintains a stack
of return destinations.

   If a jump is taken, it always goes to the most recently registered
destination. It may revert to the previously registered destination
only when the current one is cleared. This organization provides the
necessary flexibility for multiple clients and recursion, but it
necessitates a protocol whereby each registration of a destination must
be explicitly cleared exactly once.

   The following functions implement these two features.

 -- Function: int avm_setjmp ()
     This function specifies the point to which control will pass by a
     non-local jump if there is insufficient memory to complete a
     subsequent `malloc' or `realloc' operation. Only the operations
     that take place while memory is being managed due to
     `avm_manage_memory' are affected (*note Memory leaks::).

     The function returns zero when it is called normally and
     successfully registers the return point.

     It returns a non-zero value when it has been entered by a non-local
     jump (i.e., when `malloc' or `realloc' has reported insufficient
     memory while memory management is active), or when the return
     point could not be successfully registered due to insufficient
     memory. The client need not distinguish between these two cases,
     because both correspond to memory overflows and the destination
     must be cleared by `avm_clearjmp' regardless.

     When a non-zero value is returned due to this function being
     reached by a non-local jump, it has the side effects of reclaiming
     all managed memory by calling `avm_free_managed_memory' and
     disabling memory management by calling `avm_dont_manage_memory'.

 -- Function: void avm_clearjmp ()
     This function cancels the effect of `avm_setjmp ()' by preventing
     further non-local jumps to its destination if the destination was
     successfully registered, or by acknowledging unsuccessful
     registration otherwise. It should be called before exiting any
     function that calls `avm_setjmp ()' or anomalous results may ensue.

   The memory management functions `avm_manage_memory' and
`avm_dont_manage_memory' can be useful with or without `avm_setjmp',
depending on how much of a workaround is needed for a given library. If
a library does not abort on memory overflows, there is no need to use
`avm_setjmp', while it may still be appropriate to use the other
functions against memory leaks.

   Calling `avm_clearjmp' is particularly important if a client module
with memory management that doesn't use `avm_setjmp' is invoked
subsequently to one that does, so that memory overflows in the latter
won't cause an attempted jump to a stale destination.

   A further complication that arises from careful consideration of
these issues is the situation of a client module that does not intend
to use `avm_setjmp' but is called (perhaps indirectly) by one that
does. The latter will have registered a return destination that remains
active and valid even if the former refrains from doing so, thereby
allowing a branch to be taken that should have been prevented.
Although it is an unusual situation, it can be accommodated by the
following function.

 -- Function: void avm_setnonjump ()
     This function temporarily inhibits non-local jumps to destinations
     previously registered by `avm_setjmp' until the next time
     `avm_clearjmp' is called. Thereafter, any previously registered
     destinations are reinstated.

   A sketch of how some of these functions might be used to cope with
library functions that would otherwise terminate the program in the
event of a memory overflow is shown below. The GNU `libc' reference
manual contains a related discussion of non-local jumps.

     #include <avm/mwrap.h>
     ...

     int
     function foobar (foo, bar)
     ...
     {
     char *my_data;

       my_data = (char *) malloc (100);
       if (avm_setjmp () != 0)
         {
           avm_clearjmp ();
           avm_turn_on_stdout ();       /* reaching here */
           free (my_data);              /* means malloc  */
           return ABNORMAL_STATUS;      /* failed below  */
         }
       avm_turn_off_stdout ();
       avm_manage_memory ();
       ...
       call_library_functions (foo, bar);    /* may jump */
       ...                                   /* to above */
       avm_free_managed_memory ();
       avm_turn_on_stdout ();
       avm_clearjmp ();
       free (my_data);            /* reaching here means */
       return OK_STATUS;          /* jumping wasn't done */
     }

   Portability issues with these functions are not well known at this writing.
If the configuration script for `avram' fails to detect the required
features in `setjmp.h' on the host system, conditional compilation
directives will disable the functions `avm_setjmp', `avm_clearjmp', and
`avm_setnonjmp'.  However, it may still be possible for the other
`avm_'* memory management functions to be configured.

   If `setjmp' is not configured, the `avm_setjmp' function is still
callable but will always return a value of zero, and will provide no
protection against external library functions aborting the program. The
other two will perform no operation and return.


File: avram.info,  Node: Character Table,  Next: Reference Implementations,  Prev: Library Reference,  Up: Top

Appendix A Character Table
**************************

This table lists the representations used by `avram' for characters.
The left column shows the character code in decimal. For printable
characters, the middle column shows the character. The right column
shows the representation used. For example, the letter `A' has
character code 65, and the representation
`(nil,(((nil,(nil,(nil,nil))),nil),(nil,nil)))'.

   These representations were generated automatically to meet various
helpful criteria, and are not expected to change in future releases. No
character representation coincides with the representations used for
boolean values, natural numbers, character strings, pairs of characters,
or certain other data types beyond the scope of this document. An easy
algorithm for lexical sorting is possible. Subject to these criteria,
the smallest possible trees were chosen.


       0   (nil,(nil,(nil,((nil,nil),(nil,nil)))))
       1   (nil,(nil,((nil,nil),(nil,nil))))
       2   (nil,(nil,((nil,nil),(nil,(nil,nil)))))
       3   (nil,(nil,((nil,(nil,nil)),(nil,nil))))
       4   (nil,(nil,(((nil,nil),nil),(nil,nil))))
       5   (nil,(nil,(((nil,nil),(nil,nil)),nil)))
       6   (nil,(nil,((((nil,nil),(nil,nil)),nil),nil)))
       7   (nil,((nil,nil),(nil,nil)))
       8   (nil,((nil,nil),(nil,(nil,nil))))
       9   (nil,((nil,nil),(nil,(nil,(nil,nil)))))
      10   (nil,((nil,nil),(nil,(nil,(nil,(nil,nil))))))
      11   (nil,((nil,nil),(nil,((nil,nil),(nil,nil)))))
      12   (nil,((nil,nil),(nil,((nil,(nil,nil)),nil))))
      13   (nil,((nil,nil),(nil,(((nil,nil),nil),nil))))
      14   (nil,((nil,nil),((nil,nil),(nil,nil))))
      15   (nil,((nil,nil),((nil,nil),(nil,(nil,nil)))))
      16   (nil,((nil,nil),((nil,(nil,nil)),nil)))
      17   (nil,((nil,nil),((nil,(nil,nil)),(nil,nil))))
      18   (nil,((nil,nil),((nil,(nil,(nil,nil))),nil)))
      19   (nil,((nil,nil),(((nil,nil),nil),(nil,nil))))
      20   (nil,((nil,nil),(((nil,nil),(nil,nil)),nil)))
      21   (nil,((nil,(nil,nil)),(nil,nil)))
      22   (nil,((nil,(nil,nil)),(nil,(nil,nil))))
      23   (nil,((nil,(nil,nil)),(nil,(nil,(nil,nil)))))
      24   (nil,((nil,(nil,nil)),(nil,((nil,nil),nil))))
      25   (nil,((nil,(nil,nil)),((nil,nil),nil)))
      26   (nil,((nil,(nil,nil)),((nil,nil),(nil,nil))))
      27   (nil,((nil,(nil,nil)),((nil,(nil,nil)),nil)))
      28   (nil,((nil,(nil,nil)),(((nil,nil),nil),nil)))
      29   (nil,((nil,(nil,(nil,nil))),(nil,nil)))
      30   (nil,((nil,(nil,(nil,nil))),(nil,(nil,nil))))
      31   (nil,((nil,(nil,(nil,nil))),((nil,nil),nil)))
      32   (nil,((nil,(nil,(nil,(nil,nil)))),(nil,nil)))
      33 ! (nil,((nil,(nil,((nil,nil),nil))),(nil,nil)))
      34 " (nil,((nil,(nil,((nil,nil),(nil,nil)))),nil))
      35 # (nil,((nil,((nil,nil),nil)),(nil,nil)))
      36 $ (nil,((nil,((nil,nil),nil)),(nil,(nil,nil))))
      37 % (nil,((nil,((nil,nil),(nil,nil))),nil))
      38 & (nil,((nil,((nil,nil),(nil,nil))),(nil,nil)))
      39 ' (nil,((nil,((nil,nil),(nil,(nil,nil)))),nil))
      40 ( (nil,((nil,((nil,(nil,nil)),nil)),(nil,nil)))
      41 ) (nil,((nil,((nil,(nil,nil)),(nil,nil))),nil))
      42 * (nil,((nil,(((nil,nil),nil),nil)),(nil,nil)))
      43 + (nil,((nil,(((nil,nil),nil),(nil,nil))),nil))
      44 , (nil,((nil,(((nil,nil),(nil,nil)),nil)),nil))
      45 - (nil,(((nil,nil),nil),(nil,nil)))
      46 . (nil,(((nil,nil),nil),(nil,(nil,nil))))
      47 / (nil,(((nil,nil),nil),(nil,(nil,(nil,nil)))))
      48 0 (nil,(((nil,nil),nil),((nil,nil),(nil,nil))))
      49 1 (nil,(((nil,nil),nil),((nil,(nil,nil)),nil)))
      50 2 (nil,(((nil,nil),(nil,nil)),nil))
      51 3 (nil,(((nil,nil),(nil,nil)),(nil,nil)))
      52 4 (nil,(((nil,nil),(nil,nil)),(nil,(nil,nil))))
      53 5 (nil,(((nil,nil),(nil,nil)),((nil,nil),nil)))
      54 6 (nil,(((nil,nil),(nil,(nil,nil))),nil))
      55 7 (nil,(((nil,nil),(nil,(nil,nil))),(nil,nil)))
      56 8 (nil,(((nil,nil),(nil,(nil,(nil,nil)))),nil))
      57 9 (nil,(((nil,nil),((nil,nil),nil)),(nil,nil)))
      58 : (nil,(((nil,nil),((nil,nil),(nil,nil))),nil))
      59 ; (nil,(((nil,nil),((nil,(nil,nil)),nil)),nil))
      60 < (nil,(((nil,(nil,nil)),nil),(nil,nil)))
      61 = (nil,(((nil,(nil,nil)),nil),(nil,(nil,nil))))
      62 > (nil,(((nil,(nil,nil)),(nil,nil)),nil))
      63 ? (nil,(((nil,(nil,nil)),(nil,nil)),(nil,nil)))
      64 @ (nil,(((nil,(nil,nil)),(nil,(nil,nil))),nil))
      65 A (nil,(((nil,(nil,(nil,nil))),nil),(nil,nil)))
      66 B (nil,(((nil,(nil,(nil,nil))),(nil,nil)),nil))
      67 C (nil,(((nil,((nil,nil),nil)),nil),(nil,nil)))
      68 D (nil,(((nil,((nil,nil),nil)),(nil,nil)),nil))
      69 E (nil,((((nil,nil),nil),nil),(nil,nil)))
      70 F (nil,((((nil,nil),nil),nil),(nil,(nil,nil))))
      71 G (nil,((((nil,nil),nil),(nil,nil)),nil))
      72 H (nil,((((nil,nil),nil),(nil,nil)),(nil,nil)))
      73 I (nil,((((nil,nil),nil),(nil,(nil,nil))),nil))
      74 J (nil,((((nil,nil),(nil,nil)),nil),(nil,nil)))
      75 K (nil,((((nil,nil),(nil,nil)),(nil,nil)),nil))
      76 L (nil,((((nil,(nil,nil)),nil),nil),(nil,nil)))
      77 M (nil,((((nil,(nil,nil)),nil),(nil,nil)),nil))
      78 N (nil,(((((nil,nil),nil),nil),nil),(nil,nil)))
      79 O (nil,(((((nil,nil),nil),nil),(nil,nil)),nil))
      80 P ((nil,nil),(nil,nil))
      81 Q ((nil,nil),(nil,(nil,nil)))
      82 R ((nil,nil),(nil,(nil,(nil,nil))))
      83 S ((nil,nil),(nil,(nil,(nil,(nil,nil)))))
      84 T ((nil,nil),(nil,(nil,(nil,(nil,(nil,nil))))))
      85 U ((nil,nil),(nil,(nil,((nil,(nil,nil)),nil))))
      86 V ((nil,nil),(nil,(nil,(((nil,nil),nil),nil))))
      87 W ((nil,nil),(nil,((nil,nil),(nil,nil))))
      88 X ((nil,nil),(nil,((nil,(nil,nil)),nil)))
      89 Y ((nil,nil),(nil,((nil,(nil,nil)),(nil,nil))))
      90 Z ((nil,nil),(nil,((nil,(nil,(nil,nil))),nil)))
      91 [ ((nil,nil),(nil,((nil,((nil,nil),nil)),nil)))
      92 \ ((nil,nil),(nil,(((nil,nil),nil),nil)))
      93 ] ((nil,nil),(nil,(((nil,nil),nil),(nil,nil))))
      94 ^ ((nil,nil),(nil,(((nil,nil),(nil,nil)),nil)))
      95 _ ((nil,nil),(nil,(((nil,(nil,nil)),nil),nil)))
      96 ` ((nil,nil),(nil,((((nil,nil),nil),nil),nil)))
      97 a ((nil,nil),((nil,nil),(nil,nil)))
      98 b ((nil,nil),((nil,nil),(nil,(nil,nil))))
      99 c ((nil,nil),((nil,nil),(nil,(nil,(nil,nil)))))
     100 d ((nil,nil),((nil,nil),((nil,nil),(nil,nil))))
     101 e ((nil,nil),((nil,nil),((nil,(nil,nil)),nil)))
     102 f ((nil,nil),((nil,(nil,nil)),nil))
     103 g ((nil,nil),((nil,(nil,nil)),(nil,nil)))
     104 h ((nil,nil),((nil,(nil,nil)),(nil,(nil,nil))))
     105 i ((nil,nil),((nil,(nil,nil)),((nil,nil),nil)))
     106 j ((nil,nil),((nil,(nil,(nil,nil))),nil))
     107 k ((nil,nil),((nil,(nil,(nil,nil))),(nil,nil)))
     108 l ((nil,nil),((nil,(nil,(nil,(nil,nil)))),nil))
     109 m ((nil,nil),((nil,((nil,nil),nil)),(nil,nil)))
     110 n ((nil,nil),((nil,((nil,nil),(nil,nil))),nil))
     111 o ((nil,nil),((nil,((nil,(nil,nil)),nil)),nil))
     112 p ((nil,nil),(((nil,nil),nil),(nil,nil)))
     113 q ((nil,nil),(((nil,nil),nil),(nil,(nil,nil))))
     114 r ((nil,nil),(((nil,nil),(nil,nil)),nil))
     115 s ((nil,nil),(((nil,nil),(nil,nil)),(nil,nil)))
     116 t ((nil,nil),(((nil,nil),(nil,(nil,nil))),nil))
     117 u ((nil,nil),(((nil,(nil,nil)),nil),(nil,nil)))
     118 v ((nil,nil),(((nil,(nil,nil)),(nil,nil)),nil))
     119 w ((nil,nil),((((nil,nil),nil),nil),(nil,nil)))
     120 x ((nil,nil),((((nil,nil),nil),(nil,nil)),nil))
     121 y ((nil,nil),(((((nil,nil),nil),nil),nil),nil))
     122 z ((nil,(nil,nil)),(nil,nil))
     123 { ((nil,(nil,nil)),(nil,(nil,(nil,nil))))
     124 | ((nil,(nil,nil)),(nil,(nil,(nil,(nil,nil)))))
     125 } ((nil,(nil,nil)),(nil,((nil,nil),nil)))
     126 ~ ((nil,(nil,nil)),(nil,((nil,nil),(nil,nil))))
     127   ((nil,(nil,nil)),(nil,((nil,(nil,nil)),nil)))
     128   ((nil,(nil,nil)),((nil,nil),(nil,nil)))
     129   ((nil,(nil,nil)),((nil,nil),(nil,(nil,nil))))
     130   ((nil,(nil,nil)),((nil,(nil,nil)),nil))
     131   ((nil,(nil,nil)),((nil,(nil,nil)),(nil,nil)))
     132   ((nil,(nil,nil)),((nil,(nil,(nil,nil))),nil))
     133   ((nil,(nil,nil)),(((nil,nil),nil),(nil,nil)))
     134   ((nil,(nil,nil)),(((nil,nil),(nil,nil)),nil))
     135   ((nil,(nil,(nil,nil))),(nil,nil))
     136   ((nil,(nil,(nil,nil))),(nil,(nil,nil)))
     137   ((nil,(nil,(nil,nil))),(nil,(nil,(nil,nil))))
     138   ((nil,(nil,(nil,nil))),(nil,((nil,nil),nil)))
     139   ((nil,(nil,(nil,nil))),((nil,nil),(nil,nil)))
     140   ((nil,(nil,(nil,nil))),((nil,(nil,nil)),nil))
     141   ((nil,(nil,(nil,(nil,nil)))),(nil,nil))
     142   ((nil,(nil,(nil,(nil,nil)))),(nil,(nil,nil)))
     143   ((nil,(nil,(nil,(nil,nil)))),((nil,nil),nil))
     144   ((nil,(nil,(nil,(nil,(nil,nil))))),(nil,nil))
     145   ((nil,(nil,(nil,((nil,nil),nil)))),(nil,nil))
     146   ((nil,(nil,((nil,nil),nil))),(nil,nil))
     147   ((nil,(nil,((nil,nil),(nil,nil)))),(nil,nil))
     148   ((nil,(nil,((nil,(nil,nil)),nil))),(nil,nil))
     149   ((nil,(nil,(((nil,nil),nil),nil))),(nil,nil))
     150   ((nil,((nil,nil),nil)),(nil,nil))
     151   ((nil,((nil,nil),nil)),(nil,(nil,nil)))
     152   ((nil,((nil,nil),nil)),(nil,(nil,(nil,nil))))
     153   ((nil,((nil,nil),nil)),(nil,((nil,nil),nil)))
     154   ((nil,((nil,nil),nil)),((nil,nil),(nil,nil)))
     155   ((nil,((nil,nil),nil)),((nil,(nil,nil)),nil))
     156   ((nil,((nil,nil),(nil,nil))),(nil,nil))
     157   ((nil,((nil,nil),(nil,nil))),(nil,(nil,nil)))
     158   ((nil,((nil,nil),(nil,(nil,nil)))),(nil,nil))
     159   ((nil,((nil,nil),((nil,nil),nil))),(nil,nil))
     160   ((nil,((nil,(nil,nil)),nil)),(nil,nil))
     161   ((nil,((nil,(nil,nil)),nil)),(nil,(nil,nil)))
     162   ((nil,((nil,(nil,nil)),nil)),((nil,nil),nil))
     163   ((nil,((nil,(nil,nil)),(nil,nil))),(nil,nil))
     164   ((nil,((nil,(nil,(nil,nil))),nil)),(nil,nil))
     165   ((nil,((nil,((nil,nil),nil)),nil)),(nil,nil))
     166   ((nil,(((nil,nil),nil),nil)),(nil,nil))
     167   ((nil,(((nil,nil),nil),(nil,nil))),(nil,nil))
     168   ((nil,(((nil,nil),(nil,nil)),nil)),(nil,nil))
     169   ((nil,(((nil,(nil,nil)),nil),nil)),(nil,nil))
     170   ((nil,((((nil,nil),nil),nil),nil)),(nil,nil))
     171   (((nil,nil),nil),(nil,nil))
     172   (((nil,nil),nil),(nil,(nil,nil)))
     173   (((nil,nil),nil),(nil,(nil,(nil,nil))))
     174   (((nil,nil),nil),(nil,(nil,(nil,(nil,nil)))))
     175   (((nil,nil),nil),(nil,(nil,((nil,nil),nil))))
     176   (((nil,nil),nil),(nil,((nil,nil),nil)))
     177   (((nil,nil),nil),(nil,((nil,nil),(nil,nil))))
     178   (((nil,nil),nil),(nil,((nil,(nil,nil)),nil)))
     179   (((nil,nil),nil),(nil,(((nil,nil),nil),nil)))
     180   (((nil,nil),nil),((nil,nil),(nil,nil)))
     181   (((nil,nil),nil),((nil,nil),(nil,(nil,nil))))
     182   (((nil,nil),nil),((nil,(nil,nil)),nil))
     183   (((nil,nil),nil),((nil,(nil,nil)),(nil,nil)))
     184   (((nil,nil),nil),((nil,(nil,(nil,nil))),nil))
     185   (((nil,nil),nil),(((nil,nil),nil),(nil,nil)))
     186   (((nil,nil),nil),(((nil,nil),(nil,nil)),nil))
     187   (((nil,nil),(nil,nil)),(nil,nil))
     188   (((nil,nil),(nil,nil)),(nil,(nil,nil)))
     189   (((nil,nil),(nil,nil)),(nil,(nil,(nil,nil))))
     190   (((nil,nil),(nil,nil)),(nil,((nil,nil),nil)))
     191   (((nil,nil),(nil,nil)),((nil,(nil,nil)),nil))
     192   (((nil,nil),(nil,(nil,nil))),(nil,nil))
     193   (((nil,nil),(nil,(nil,nil))),(nil,(nil,nil)))
     194   (((nil,nil),(nil,(nil,(nil,nil)))),(nil,nil))
     195   (((nil,nil),(nil,((nil,nil),nil))),(nil,nil))
     196   (((nil,nil),((nil,nil),nil)),(nil,nil))
     197   (((nil,nil),((nil,nil),nil)),(nil,(nil,nil)))
     198   (((nil,nil),((nil,nil),(nil,nil))),(nil,nil))
     199   (((nil,nil),((nil,(nil,nil)),nil)),(nil,nil))
     200   (((nil,nil),(((nil,nil),nil),nil)),(nil,nil))
     201   (((nil,(nil,nil)),nil),(nil,nil))
     202   (((nil,(nil,nil)),nil),(nil,(nil,nil)))
     203   (((nil,(nil,nil)),nil),(nil,(nil,(nil,nil))))
     204   (((nil,(nil,nil)),nil),(nil,((nil,nil),nil)))
     205   (((nil,(nil,nil)),nil),((nil,nil),(nil,nil)))
     206   (((nil,(nil,nil)),nil),((nil,(nil,nil)),nil))
     207   (((nil,(nil,nil)),(nil,nil)),(nil,nil))
     208   (((nil,(nil,nil)),(nil,nil)),(nil,(nil,nil)))
     209   (((nil,(nil,nil)),(nil,(nil,nil))),(nil,nil))
     210   (((nil,(nil,nil)),((nil,nil),nil)),(nil,nil))
     211   (((nil,(nil,(nil,nil))),nil),(nil,nil))
     212   (((nil,(nil,(nil,nil))),nil),(nil,(nil,nil)))
     213   (((nil,(nil,(nil,nil))),nil),((nil,nil),nil))
     214   (((nil,(nil,(nil,nil))),(nil,nil)),(nil,nil))
     215   (((nil,(nil,(nil,(nil,nil)))),nil),(nil,nil))
     216   (((nil,(nil,((nil,nil),nil))),nil),(nil,nil))
     217   (((nil,((nil,nil),nil)),nil),(nil,nil))
     218   (((nil,((nil,nil),nil)),nil),(nil,(nil,nil)))
     219   (((nil,((nil,nil),nil)),nil),((nil,nil),nil))
     220   (((nil,((nil,nil),nil)),(nil,nil)),(nil,nil))
     221   (((nil,((nil,nil),(nil,nil))),nil),(nil,nil))
     222   (((nil,((nil,(nil,nil)),nil)),nil),(nil,nil))
     223   (((nil,(((nil,nil),nil),nil)),nil),(nil,nil))
     224   ((((nil,nil),nil),nil),(nil,nil))
     225   ((((nil,nil),nil),nil),(nil,(nil,nil)))
     226   ((((nil,nil),nil),nil),(nil,(nil,(nil,nil))))
     227   ((((nil,nil),nil),nil),(nil,((nil,nil),nil)))
     228   ((((nil,nil),nil),nil),((nil,nil),nil))
     229   ((((nil,nil),nil),nil),((nil,nil),(nil,nil)))
     230   ((((nil,nil),nil),nil),((nil,(nil,nil)),nil))
     231   ((((nil,nil),nil),nil),(((nil,nil),nil),nil))
     232   ((((nil,nil),nil),(nil,nil)),(nil,nil))
     233   ((((nil,nil),nil),(nil,nil)),(nil,(nil,nil)))
     234   ((((nil,nil),nil),(nil,(nil,nil))),(nil,nil))
     235   ((((nil,nil),nil),((nil,nil),nil)),(nil,nil))
     236   ((((nil,nil),(nil,nil)),nil),(nil,nil))
     237   ((((nil,nil),(nil,nil)),nil),(nil,(nil,nil)))
     238   ((((nil,nil),(nil,nil)),(nil,nil)),(nil,nil))
     239   ((((nil,nil),(nil,(nil,nil))),nil),(nil,nil))
     240   ((((nil,nil),((nil,nil),nil)),nil),(nil,nil))
     241   ((((nil,(nil,nil)),nil),nil),(nil,nil))
     242   ((((nil,(nil,nil)),nil),nil),(nil,(nil,nil)))
     243   ((((nil,(nil,nil)),nil),nil),((nil,nil),nil))
     244   ((((nil,(nil,nil)),nil),(nil,nil)),(nil,nil))
     245   ((((nil,(nil,nil)),(nil,nil)),nil),(nil,nil))
     246   ((((nil,(nil,(nil,nil))),nil),nil),(nil,nil))
     247   ((((nil,((nil,nil),nil)),nil),nil),(nil,nil))
     248   (((((nil,nil),nil),nil),nil),(nil,nil))
     249   (((((nil,nil),nil),nil),nil),(nil,(nil,nil)))
     250   (((((nil,nil),nil),nil),nil),((nil,nil),nil))
     251   (((((nil,nil),nil),nil),(nil,nil)),(nil,nil))
     252   (((((nil,nil),nil),(nil,nil)),nil),(nil,nil))
     253   (((((nil,nil),(nil,nil)),nil),nil),(nil,nil))
     254   (((((nil,(nil,nil)),nil),nil),nil),(nil,nil))
     255   ((((((nil,nil),nil),nil),nil),nil),(nil,nil))


File: avram.info,  Node: Reference Implementations,  Next: Changes,  Prev: Character Table,  Up: Top

Appendix B Reference Implementations
************************************

This appendix contains some `silly' source code for several functions
that are mentioned in *note Virtual Code Semantics::, for specifying
the virtual machine code semantics, namely `pairwise', `transition',
`insert' and `replace'.

   The intention is to specify the virtual machine mathematically with a
minimum of hand waving, by using only simple equations and small
fragments of `silly' code, which has a straightforward semantics.
However, the `silly' code fragments are more significant in some cases
than what could fit into a few lines or be mechanically derived from an
equation.

   The purpose of this appendix is therefore to avoid leaving any gaps
in the construction by demonstrating that everything mentioned can be
done. None of this code is needed for any practical purpose, because its
functionality is inherent in the virtual machine, but it shows how
certain operations would be specified if they were not built in.

* Menu:

* Pairwise::
* Insert::
* Replace::
* Transition::


File: avram.info,  Node: Pairwise,  Next: Insert,  Prev: Reference Implementations,  Up: Reference Implementations

B.1 Pairwise
============

This `silly' code fragment is mentioned in *note Reduce::, in the
discussion of `reduce', and is provided as an example of a solution to
equations _E1_ to _E3_. It is written in the style of a higher order
function, in that it takes a function `F' as an argument and returns
another function, [[`pairwise']] `F' as a result.


     self     = left
     argument = right
     head     = left
     tail     = right

     pairwise =

     compose(
        refer,
        compose(
           bu(
              conditional,
              conditional(argument,compose(tail,argument),constant nil)),
           couple(
              (hired couple)(
                 (hired compose)(
                    identity,
                    constant (hired fan head)(
                       argument,
                       compose(tail,argument))),
                 constant (hired meta)(
                    self,
                    compose(tail,compose(tail,argument)))),
              constant argument)))

To see how this works, one should evaluate it symbolically with an
unknown `F', which will result in some `silly' pseudocode, and then
evaluate that symbolically with some sample lists.


File: avram.info,  Node: Insert,  Next: Replace,  Prev: Pairwise,  Up: Reference Implementations

B.2 Insert
==========

This function is mentioned in *note Sort::, on sorting. It takes the
virtual code for a partial order relational operator and returns the
code for a function of two arguments. The left argument is a list item
and the right argument is a list of items of the same type, which is
already sorted with respect to the relational operator given as the
argument to `insert'. The result of the function returned by `insert'
is a list similar to its right argument but with the left argument
inserted in the proper position to maintain the order.

   This code makes use of the `self', `argument', `head' and `tail'
declarations associated with `pairwise'.


     insert =

     bu(compose,refer) (hired conditional)(
        constant compose(right,argument),
        couple(
           (hired conditional)(
              (hired compose)(
                 identity,
                 constant compose(
                    couple(left,compose(head,right)),
                    argument)),
              constant (
                 argument,
                 couple(
                    compose(head,compose(right,argument)),
                    (hired meta)(
                       self,
                       couple(
                          compose(left,argument),
                          compose(tail,compose(right,argument))))))),
           constant argument))

   As with the other higher order functions in this appendix, the only
feasible ways to verify it would be either by formal proof or by some
form of symbolic interpretation.


File: avram.info,  Node: Replace,  Next: Transition,  Prev: Insert,  Up: Reference Implementations

B.3 Replace
===========

This code is needed in the discussion of assignment in *note
Assignment::.  where it serves as a solution to equation _E0_. The idea
is that the function takes an argument of the form
`((LOCATIONS,VALUES),STORE)' and returns the store with the values
stored at the locations indicated.


     locations = compose(left,compose(left,argument))
     values    = compose(right,compose(left,argument))
     store     = compose(right,argument)

     replace =

     refer conditional(
        store,
        (
           conditional(
              compose(left,locations),
              (
                 conditional(
                    compose(right,locations),
                    (
                       (hired meta)(
                          self,
                          couple(
                             (hired fan right)(locations,values),
                             (hired meta)(
                                self,
                                couple(
                                   (hired fan left)(locations,values),
                                   store)))),
                       couple(
                          (hired meta)(
                             self,
                             couple(
                                couple(compose(left,locations),values),
                                compose(left,store))),
                          compose(right,store)))),
                 conditional(
                    compose(right,locations),
                    (
                       couple(
                          compose(left,store),
                          (hired meta)(
                             self,
                             couple(
                                couple(compose(right,locations),values),
                                compose(right,store)))),
                       values)))),
              (hired meta)(
                 self,
                 couple(couple(locations,values),constant (nil,nil)))))


File: avram.info,  Node: Transition,  Prev: Replace,  Up: Reference Implementations

B.4 Transition
==============

This code is relevant to the discussion of `transfer' in *note
Transfer::, where its specification is described in detail. When this
code is evaluated on a virtual code application `F', the result is the
code for a transition function that takes one configuration to the next
in the course of evaluating a transfer function, as specified in
equations _E7_ to _E9_.  


     output_buffer = compose(left,argument)
     input_buffer = compose(right,compose(right,argument))
     active = compose(left,compose(right,argument))
     state = compose(left,active)
     output = compose(right,active)

     transition =

     bu(compose,refer) (hired bu(conditional,active))(
        (hired conditional)(
           constant input_buffer,
           bu(compose,(fan bu(hired meta,self))) (hired apply)(
              constant fan bu(couple,couple(output,output_buffer)),
              couple (fan bu(compose,couple))(
                 couple(
                    (hired apply)(
                       hired,
                       constant (state,compose(head,input_buffer))),
                    constant compose(tail,input_buffer)),
                 couple(
                    (hired apply)(hired,constant(state,constant nil)),
                    constant constant nil)))),
        constant compose(flat,compose(reverse,output_buffer)))


File: avram.info,  Node: Changes,  Next: External Libraries,  Prev: Reference Implementations,  Up: Top

Appendix C Changes
******************

This section is reserved for brief updates due to changes in the
software that may be important enough to note temporarily until more
thorough revisions to the document can be made.

   The lack of content here indicates that the current version is either
completely up to date or in such a sorry state of neglect that even
this section is obsolete.


File: avram.info,  Node: External Libraries,  Next: Copying,  Prev: Changes,  Up: Top

Appendix D External Libraries
*****************************

Various functions are callable from virtual code applications by way of
the `library' combinator as explained in *note Library combinator::. An
expression (shown in `silly' syntax) of the form `library('foo','bar')
x' applies a function named `'bar'' from a library named `'foo'' to an
argument `x'.

   A brief overview of the libraries and functions can always be had by
executing

     $ avram --external-libraries

The listing displayed by this command may show some that are not
included here if this version of the documentation is not current or
your installation has been locally enhanced. It may also lack some that
are documented here if your installation is not fully equipped.

   Although the overview from the command line is adequate for a
reminder, it is not informative enough to explain how each function
should be used. The purpose of this section is to provide this
information in greater detail.

   Some general comments are applicable to all libraries.

   Each library documented in this section can generate error messages
in the event of exceptional conditions, that are documented
individually.  In addition to those, it's also possible for any library
function to return error messages of 

     <'unrecognized library'>
     <'unrecognized XXXX function name'>

where XXXX is the name of a library.  These indicate either that the
library name is invalid, or the library name is valid but the function
name is invalid, or that they're both valid but the library wasn't
detected on the host when `avram' was compiled. A virtual code
application can always avoid these errors by testing for the
availability of a function using the `have' combinator (*note Have
combinator::).

   In addition, any library function that operates on numerical values
or lists thereof can return these messages in cases of invalid input.  

     <'missing value'>
     <'invalid value'>
     <'bad vector specification'>
     <'bad matrix specification'>

These messages indicate that an input parameter that was required to be
a valid representation of a floating point number, a vector, or a
matrix was something other than that (*note Type Conversions::).  The
last could also occur if a parameter that is required to be a square
matrix has unequal numbers of rows and columns.

* Menu:

* bes::       Bessel functions
* complex::   native complex arithmetic
* fftw::      fast Fourier transforms
* glpk::      simplex linear programming
* gsldif::    numerical differentiation
* gslevu::    series acceleration
* gslint::    numerical integration
* harminv::   harmonic inversion
* kinsol::    constrained non-linear optimization
* lapack::    linear algebra
* math::      native floating point arithmetic
* mtwist::    random number generation
* minpack::   non-linear optimization
* mpfr::      arbitrary precision arithmetic
* lpsolve::   mixed integer programming
* rmath::     statistical and special functions
* umf::       sparse matrices


File: avram.info,  Node: bes,  Next: complex,  Prev: External Libraries,  Up: External Libraries

D.1 `bes'
=========

An interface to the Bessel functions as defined in the GNU Scientific
Library (gsl) is available to virtual code applications by invoking a
function of the form

     library('bes',f)

where f is a character string identifying the Bessel function family.
All functions in this library return a floating point number encoded as
in *note math::.

* Menu:

* Bessel function calling conventions::
* Bessel function errors::


File: avram.info,  Node: Bessel function calling conventions,  Next: Bessel function errors,  Prev: bes,  Up: bes

D.1.1 Bessel function calling conventions
-----------------------------------------

The virtual code interface simplifies the gsl C language API by
excluding the facilities for error estimates, omitting certain array
valued functions, and subsuming sets of related functions within common
ones where possible.

   The functions with names in the following group take an argument of
the form `(n,x)', where `n' identifies the member of the function
family, and `x' is the argument to the function.

   * `J' regular cylindrical Bessel functions

   * `Y' irregular cylindrical Bessel functions

   * `I' regular modified cylindrical Bessel functions

   * `K' irregular modified cylindrical Bessel functions

   For these functions, `n' can be either a natural number encoded as
in *note Representation of Numeric and Textual Data::, or a floating
point number encoded as in *note math::. The latter case specifies
functions of a fractional order. The relevant gsl function is called
based on the value and type of the parameter.

   Two further related families of functions follow the same calling
convention.

   * `Isc' scaled regular modified cylindrical Bessel functions

   * `Ksc' scaled irregular modified cylindrical Bessel functions

The foregoing functions are related to those above by an exponential
scale factor as documented in the gsl reference manual.

   Functions with names in the following group also take an argument of
the form `(n,x)', but are not defined for fractional orders and so
require a natural number for `n'.

   * `j' regular spherical Bessel functions

   * `y' irregular spherical Bessel functions

   * `isc' regular modified spherical Bessel functions

   * `ksc' irregular modified spherical Bessel functions

   The functions in the remaining group follow idiosyncratic calling
conventions.

   * `zJ0', `zJ1' These take a natural number `n' and return the `n'th
     root of the regular cylindrical Bessel functions of order 0 or 1,
     respectively.

   * `zJnu' This takes a pair `(nu,n)' where `nu' is the (fractional)
     order of a regular cylindrical Bessel function, `n' is a natural
     number. It returns the `n'th zero of the function.

   * `lnKnu' This takes a pair of floating point numbers `(nu,x)' where
     `nu' is the (fractional) order of an irregular modified
     cylindrical Bessel and `x' is the argument to the function, and it
     returns the natural log of the function.


File: avram.info,  Node: Bessel function errors,  Prev: Bessel function calling conventions,  Up: bes

D.1.2 Bessel function errors
----------------------------

Memory overflows and unrecognized function names can happen as with
other library interfaces. A message of 

     <'bad bessel function call'>

means that invalid input parameters were given, such as a fractional
order to a function family that is defined only for natural orders.


File: avram.info,  Node: complex,  Next: fftw,  Prev: bes,  Up: External Libraries

D.2 `complex'
=============

Complex numbers are represented according to the ISO C standard as arrays
of two IEEE double precision floating point numbers of 8 bytes each,
with the number representing the real part first.

   A small selection of operations on complex numbers is available by
function calls of the form `library('complex',f)'. These functions are
implemented by the host system's C library.

   One example is `library('complex','create')' which takes a pair of
floating point numbers `(X,Y)' to a complex number whose real part is X
and whose imaginary part is Y.  See *note math:: for information about
constructing floating point numbers.

   Other than that, the `complex' library functions `f' fall into three
main groups, which are the real valued unary operations, the complex
valued unary operations, and the complex valued binary operations. All
of these operations are designated by their standard C names as
documented elsewhere, such as the GNU `libc' reference manual, except
as noted.

* real valued unary operations

          creal  cimag  cabs  carg

* complex valued unary operations

          ccos   cexp    clog   conj   csin    csqrt
          ctan   csinh   ccosh  ctanh  casinh  cacosh
          catanh casin   cacos  catan

* complex valued binary operations

          cpow  vid  bus  mul  add  sub  div

   The last four correspond to the C language operators `*', `+', `-',
and `/' for complex numbers.  The functions named `vid' and `bus' are
similar to `div' and `sub', respectively, but with the operands
interchanged. That is,

     library('complex','vid') (x,y)

is equivalent to

     library('complex','div') (y,x)

   All functions in this library taking complex numbers as input may
also operate on real numbers, and binary operators can have either or
both operands real. For real operands, a value of zero is inferred as
the imaginary part. The result type of the function is the same
regardless.


File: avram.info,  Node: fftw,  Next: glpk,  Prev: complex,  Up: External Libraries

D.3 `fftw'
==========

Some functions in the `fftw' fast Fourier transform library are callable
by virtual code programs of the form `library('fftw',f)', where `f' can
be one of the following character strings.

`u_fw_dft'
     (uni-dimensional forward Discrete Fourier transform)

`u_bw_dft'
     (uni-dimensional backward Discrete Fourier transform)

`b_fw_dft'
     (bi-dimensional forward Discrete Fourier transform)

`b_bw_dft'
     (bi-dimensional backward Discrete Fourier transform)

`u_dht'
     (uni-dimensional Discrete Hartley transform)

`b_dht'
     (bi-dimensional Discrete Hartley transform)

   These stand for the discrete Fourier transform, in one dimension and
two dimensions, either backward or forward, and the discrete Hartley
transform in one dimension and two dimensions. The `fftw' library
documentation (`http://www.fftw.org') can give more information about
the meaning of these transformations.

   The interface is somewhat simplified compared to the API for the
`fftw' C library because there are no considerations of memory
management or planning, nor any provision for dimensions higher than
two.

   Furthermore, from the virtual side of the interface, these functions
operate on lists rather than arrays. The one dimensional Fourier
transforms take a list of complex numbers to a list of complex numbers
(see *note complex::), and the one dimensional Hartley transforms take
a list of reals to a list of reals (see *note math::). The two
dimensional transforms are analogous but they take a matrix represented
as a list of lists. Error messages pertaining to invalid input
documented at the beginning of this section (*note External
Libraries::) are relevant.

   Finally, unlike the native API for `fftw', these transformations are
scaled so that the backward transformation is the inverse of the
forward, and the Hartley transformations are their own inverses
(subject to roundoff error).


File: avram.info,  Node: glpk,  Next: gsldif,  Prev: fftw,  Up: External Libraries

D.4 `glpk'
==========

The `glpk' library (`ftp://ftp.gnu.org/pub/gnu/glpk/') solves linear
programming problems by the either the simplex algorithm or an interior
point method.

   The API for C client programs involves a complicated protocol with
many optional settings, which is simplified for the virtual machine
interface. Specifically, the library gives a choice of only two
functions, which can be expressed in the following forms.

     library('glpk','simplex')

     library('glpk','interior')

These functions have the same calling convention and should return
generally the same output for identical inputs, but differences in
performance, precision, and maybe correctness can be expected.  The
remainder of this section applies to both of them.

* Menu:

* glpk input parameters::
* glpk output::
* glpk errors::
* Additional glpk notes::


File: avram.info,  Node: glpk input parameters,  Next: glpk output,  Prev: glpk,  Up: glpk

D.4.1 `glpk' input parameters
-----------------------------

The argument must be a triple of the form, `(C,(M,Y))', subject to the
following specification.

   * C is a list of cost function coefficients as floating point
     numbers (see *note math::). There should be one item of C for each
     variable in the linear programming problem (Note that there is no
     additive constant, which would require one extra).

     The interpretation of C is that an assignment of non-negative
     values to the variables X is sought to make the vector inner
     product C X as small as possible.

   * M is a sparse matrix represented as a list of triples in the form 

          <((I,J),A)...>

     where I and J are row and column indices as natural numbers
     starting from 0 and A is a non-zero floating point number. The
     presence of a triple `((I,J),A)' in the list indicates that the
     I,J-th entry in the matrix has a value of A.  Missing combinations
     of I and J indicate that the corresponding entry is zero.

     The interpretation of M is that together with Y it specifies a
     system of equations the variables in the solution X must satisfy
     simultaneously, as explained below.

   * Y is a list of floating point numbers, with one number for each
     distinct value of I in M, above, needed to complete the equations.

     The interpretation of Y is that in matrix notation, the condition
     M X = Y must be met by any acceptable solution X.

     To put it another way, for each distinct value of I, the I-th item
     of Y has to equal the sum over all J of XJ A, where A is the real
     number appearing in the triple `((I,J),A)' in M, if any, and XJ is
     the J-th variable of the solution.


File: avram.info,  Node: glpk output,  Next: glpk errors,  Prev: glpk input parameters,  Up: glpk

D.4.2 `glpk' output
-------------------

If a solution meeting the constraints is found, it is returned as a
list of pairs of the form `<(I,X)...>', where each I is a natural
number and each X is a floating point number giving the value obtained
for the I-th variable numbered from zero. Any values of I that are
omitted from the list indicate that the corresponding variable has a
value of zero.

   If no solution is found due to infeasibility or because `glpk' just
didn't find one, an empty list is returned. The lack of a solution is
not treated as an exceptional condition.


File: avram.info,  Node: glpk errors,  Next: Additional glpk notes,  Prev: glpk output,  Up: glpk

D.4.3 `glpk' errors
-------------------

Possible error messages are

     <'bad glpk specification'>

which means that the input did not conform to the description given
above, and

     <'memory overflow'>

   It is not considered an exceptional condition for no feasible
solution to exist, and in that case an empty list is returned.

   The `glpk' documentation gives no assurance as to the correctness of
reported solutions, so the user should also take the possibility of
incorrect results into account.


File: avram.info,  Node: Additional glpk notes,  Prev: glpk errors,  Up: glpk

D.4.4 Additional `glpk' notes
-----------------------------

A sparse matrix representation of M is used because in practice most
linear programming problems have very sparse systems of equations.

   Only the constraint of non-negativity is admitted.  Other constraints
such as upper bounds must be effected through a change of variables if
required.

   The `glpk' library has a small memory leak, which `avram' corrects
by methods described in *note Memory leaks::.


File: avram.info,  Node: gsldif,  Next: gslevu,  Prev: glpk,  Up: External Libraries

D.5 `gsldif'
============

Numerical differentiation of a real valued function of a single real variable
can be done by a library function of the form

     library('gsldif',method)

where `method' is one of

   * `'backward''

   * `'central''

   * `'forward''

   * `'t_backward''

   * `'t_central''

   * `'t_forward''

* Menu:

* gsldif input parameters::
* gsldif output::
* gsldif exceptions::
* Additional gsldif notes::


File: avram.info,  Node: gsldif input parameters,  Next: gsldif output,  Prev: gsldif,  Up: gsldif

D.5.1 `gsldif' input parameters
-------------------------------

The argument to the functions with mnemonics of `backward', `central'
or `forward' is a pair `(F,X)', where F is the virtual machine code for
a real valued function of a real variable, and X is the input to F
where the derivative is sought. Real numbers are represented according
to *note math::.

   The argument to the functions with mnemonics of `t_backward',
`t_central' or `t_forward' is a pair `((F,T),X)', where F and X are as
above, and T is a tolerance represented as a floating point number. The
tolerance is passed through to the GNU Scientific library (GSL)
differentiation routines.

   When no tolerance is specified, the default is  `1.0e-8'.


File: avram.info,  Node: gsldif output,  Next: gsldif exceptions,  Prev: gsldif input parameters,  Up: gsldif

D.5.2 `gsldif' output
---------------------

The result returned by `library('gsldif',method) (f,x)' or
`library('gsldif',method) ((f,t),x)' is an approximation of the first
derivative of F evaluated at X.

   The result is obtained by the one of the GNU Scientific Library (GSL) functions
for numerical differentiation that matches the virtual code function
name. These functions are documented in the GSL reference manual. The
three methods should have approximately the same results but may differ
in numerical properties.


File: avram.info,  Node: gsldif exceptions,  Next: Additional gsldif notes,  Prev: gsldif output,  Up: gsldif

D.5.3 `gsldif' exceptions
-------------------------

An error message of 

     <'bad derivative specification'>

will be returned if the either the whole argument, F, or X is `nil'.

   Any error message caused by the evaluation of F will propagate to
the result.


File: avram.info,  Node: Additional gsldif notes,  Prev: gsldif exceptions,  Up: gsldif

D.5.4 Additional `gsldif' notes
-------------------------------

The function F may be any expressible virtual machine code function
that takes a real argument to a real result, including one that uses
other library functions. However, if F passes functions to other
library functions as arguments, there is a constant overhead in stack
space for each level, and a remote possibility of a segmentation fault
if they are very deeply nested.

   Numerical instability is an issue for higher derivatives (i.e.,
differentiating a function that is obtained by differentiating another
function). Some experimentation with larger tolerances may be needed.


File: avram.info,  Node: gslevu,  Next: gslint,  Prev: gsldif,  Up: External Libraries

D.6 `gslevu'
============

This library exports a pair of functions of the form

     library('gslevu','accel')

     library('gslevu','utrunc')

that take a list of real numbers X to a pair of real numbers `(S,E)'.

   The idea is that X represents the first few terms of an infinite series
whose sum converges, but only very slowly. The functions extrapolate an
estimate of the infinite summation by the Levin u-transform as
documented in the GNU Scientific Library reference manual.

   For well behaved series, considerably fewer terms are needed for an
accurate estimate than a direct summation would require.

* Menu:

* gslevu calling conventions::
* gslevu exceptions::


File: avram.info,  Node: gslevu calling conventions,  Next: gslevu exceptions,  Prev: gslevu,  Up: gslevu

D.6.1 `gslevu' calling conventions
----------------------------------

The input to either of these functions is a list of real numbers
represented as explained in *note math::.

   The result is a pair `(S,E)' holding an estimate of the sum, S, and
an estimate of the error in the sum, E, each being a real number.

   Both functions compute the same sum, S, but the `utrunc' function is
faster and more memory efficient, using a less trustworthy method of
estimating the error.


File: avram.info,  Node: gslevu exceptions,  Prev: gslevu calling conventions,  Up: gslevu

D.6.2 `gslevu' exceptions
-------------------------

If an empty list is passed as a parameter to a function in this library,
an error message of `<'empty gslevu sequence'>' is returned.

   If there is insufficient memory, an error message of `<'memory
overflow'>' is returned.

   Other than that, no exceptional conditions are relevant other than
the general ones documented at the beginning of *note External
Libraries::.


File: avram.info,  Node: gslint,  Next: harminv,  Prev: gslevu,  Up: External Libraries

D.7 `gslint'
============

An interface to a selection of numerical integration routines from the GNU
Scientific Library is provided by functions of the form

     library('gslint',q)

where q can be one of `'qng'', `'qng_tol'', `'qagx'', `'qagx_tol'',
`'qagp'', or `'qagp_tol''.

* Menu:

* gslint input parameters::
* gslint output::
* gslint exceptions::
* Additional gslint notes::


File: avram.info,  Node: gslint input parameters,  Next: gslint output,  Prev: gslint,  Up: gslint

D.7.1 `gslint' input parameters
-------------------------------

The library functions `qng' and `qagx' take an argument of the form
`(F,(A,B))', where F is a function to be integrated, A is the lower
limit, and B is the upper limit, both limits being floating point
numbers as in *note math::.

   The `qng_tol' and `qagx_tol' functions take an argument of the form
`((F,T),(A,B))', where F, A, and B are as above, and T is a specified
tolerance.

   The `qagp' and `qagp_tol' functions take arguments of the form
`(F,P)' and `((F,T),P)', respectively, where F and T are as above, and
P is an ordered list of real numbers specifying the limits of
integration along with arbitrarily many intervening breakpoints.

   The integrand F is expressed in virtual machine code, and takes a
single real argument to a real result. The argument and result of F are
required to be floating point numbers as described in *note math::. Any
expressible function of this type is acceptable, even one defined in
terms of other integrals, so that a double or triple integral can be
expressed easily, albeit a costly computation.  However, a constant
overhead in stack space is required for each nested library function
call, and there is currently no mechanism to prevent segmentation
faults due to a stack overflow.

   When no tolerance is specified, as with `qng', `qagx', and `qagp',
the tightest attainable tolerance is chosen by default, currently
`2e-14', in order find the most accurate result possible. A selection
of progressively looser tolerances is tried automatically if the
tightest one is not successful, stopping when either a solution is
found or ten orders of magnitude are covered.

   If a tolerance is explicitly specified, as with `qng_tol',
`qagx_tol' or `qagp_tol', only that tolerance is tried.


File: avram.info,  Node: gslint output,  Next: gslint exceptions,  Prev: gslint input parameters,  Up: gslint

D.7.2 `gslint' output
---------------------

In all cases, if no exception occurs, the result returned is an
approximation of the integral of F over the interval from A to B or
from the first item of P to the last.

   Results may differ in numerical properties depending on the
integration method and the tolerance used.

   * The `qagp'* and `qagx'* functions use an adaptive algorithm, whereas
     the `qng'* functions use a faster non-adaptive algorithm suitable
     only for smooth integrands.

   * Faster and maybe more accurate results are obtained for
     discontinuous or non-differentiable integrands by the `qagp'*
     integration methods if the interior points in P are chosen to
     coincide with the discontinuities or corners.

   * Larger tolerances are conducive to faster but less accurate
     results in most cases.


File: avram.info,  Node: gslint exceptions,  Next: Additional gslint notes,  Prev: gslint output,  Up: gslint

D.7.3 `gslint' exceptions
-------------------------

If an argument of an inappropriate form can be detected (such as an
empty pair or one without floating point numbers), it causes an error
message to be returned saying 

     <'bad integral specification'>

Error messages signalled by the integrand F may also be reported, as
well as any message returned by `gsl_strerror'. A typical cause for a
`gsl_strerror' message would be an explicitly specified tolerance that
is too tight. An error message of 

     <'slow convergence'>

is returned in the event of excessively many function evaluations
(currently 3600 at each tolerance level).


File: avram.info,  Node: Additional gslint notes,  Prev: gslint exceptions,  Up: gslint

D.7.4 Additional `gslint' notes
-------------------------------

The `qagx'* functions subsume the GSL variants `qags', `qagiu',
`qagil', and `qagi' for finite, semi-infinite, and infinite intervals,
which are seleted as appropriate based on the limits of integration A
and B.

   The `qagp' function reverts to the `qagx' function if there are only
two points given in P. Fewer than two will cause an error.

   The library interface code relies on the standard `setjmp' utility
found in the system header file `setjmp.h' to break out of integrals
that don't converge after excessively many function evaluations.
Non-termination has been an issue in the past with GSL integration
routines for very badly behaved integrands, and the API provides no
documented means for the user supplied integrand function to request a
halt.

   Although it is meant to be standard, a host without `setjmp' will
cause `avram' to be configured to abort the application with an error
message in the event of non-convergence. This behavior is considered
preferable to the alternative of non-termination. Usually an effective
workaround in such cases is to specify a sufficiently loose tolerance
explicitly by using one of the *`_tol' library functions.


File: avram.info,  Node: harminv,  Next: kinsol,  Prev: gslint,  Up: External Libraries

D.8 `harminv'
=============

The `harminv' library decomposes a complex valued function of a discrete
variable into a sum of decaying sinusoids given a finite sample. It
uses a method with better accuracy and convergence than Fourier
analysis or least squares curve fitting. More information is available
at `http://ab-initio.mit.edu/wiki/index.php/Harminv'.

* Menu:

* harminv input parameters::
* harminv output::
* harminv exceptions::
* Additional harminv notes::


File: avram.info,  Node: harminv input parameters,  Next: harminv output,  Prev: harminv,  Up: harminv

D.8.1 `harminv' input parameters
--------------------------------

The virtual machine interface to the `harminv' library provides only a
single function, callable as

     library('harminv','hsolve')

The input to this function is an operand of the form

     (signal,(fmin,fmax),nf)

where

   * `signal' is a list of complex numbers containing samples of the
     function to be decomposed at equal time steps (*note complex:: and
     *note Representation of Numeric and Textual Data::).

   * `fmin' and `fmax' are the band limits expressed in units of
     inverse time steps as floating point numbers (*note math::).

   * `nf' is the number of spectral basis functions expressed as a
     natural (*note Representation of Numeric and Textual Data::).

If a value of 0 is specified for `nf' a default value of

     min(300, (fmax - fmin) * n * 1.1)

is used, where `n' is the length of `signal'. The computation time
increases cubically with `nf'.


File: avram.info,  Node: harminv output,  Next: harminv exceptions,  Prev: harminv input parameters,  Up: harminv

D.8.2 `harminv' output
----------------------

The result returned by a call to

     library('harminv','hsolve')

with valid input (*note harminv input parameters::) is a list of
similar tuples of the form

     <(amplitude,frequency,decay,quality,error)...>

with all members being real valued except for the amplitudes, which are
complex. Each tuple describes a function of the form

     f(t) = A * sin (frequency * t + P) * exp (-decay * t)

such that the summation of these functions approximates the original
given signal (*note harminv input parameters::). The real amplitude `A'
and phase `P' are given by the modulus and argument of the complex
amplitude returned in the result,

     A = library('complex','cabs') amplitude
     P = library('complex','carg') amplitude

in terms of the complex library functions (*note complex::).  The error
values are measures of the goodness of fit, and the quality factors are
defined as

     quality = (pi * |frequency| / decay)

It may be useful in some applications to ignore components with quality
factors outside of a certain range.


File: avram.info,  Node: harminv exceptions,  Next: Additional harminv notes,  Prev: harminv output,  Up: harminv

D.8.3 `harminv' exceptions
--------------------------

Various exceptional conditions are possible with the `harminv' library
interface, and one of the following messages could be returned. Each of
them has the form of a list containing a single character string.

   * `unrecognized harminv function name' is reported in case of a
     function call of the form `library('harminv',f)' where `f' is
     anything other than the character string `'hsolve'', this being
     the only function in the library.

   * `bad harminv function call' is reported if the input parameters
     don't meet the specifications described in *note harminv input
     parameters::, or if `fmin' is greater than `fmax'.

   * `bad vector specification' could be the result of a list of real
     numbers rather than complex numbers being passed as a `signal'.
     Real numbers can be converted to complex numbers using the
     `create' function from the `complex' library (*note complex::).

   * `memory overflow' can occur if `avram' is operating very close to
     the limit of host memory, or perhaps if infeasibly large values
     are passed as `nf'

   * `counter overflow' is similar to a memory overflow


File: avram.info,  Node: Additional harminv notes,  Prev: harminv exceptions,  Up: harminv

D.8.4 Additional `harminv' notes
--------------------------------

The `harminv' library interface requires the `harminv' and `lapack'
libraries to be installed on the host system, and also requires
standard complex number support from the system's C library.

   The author's installation of `avram' has been compiled against the
Debian `harminv' development library package, which at this writing is
unmaintained and is missing the necessary header file `harminv-int.h',
without which compilation of files including `harminv.h' fails. Some
headers from `harminv.h' have been copied directly into
`avram-x.x.x/src/harminv.c' under the `avram' source tree to avoid this
dependence, so that `avram' will compile correctly on a Debian system.
These may need to be updated if necessary to track the `harminv' source.


File: avram.info,  Node: kinsol,  Next: lapack,  Prev: harminv,  Up: External Libraries

D.9 `kinsol'
============

The `kinsol' library (`http://www.llnl.gov/CASC/sundials/') contains
sophisticated routines for non-linear optimization and constrained
non-linear optimization, some of which are available to virtual code
applications by way of functions expressed as shown.

     library('kinsol',k)

The function name `k' is a string of the form `'XY_ZZZZZ''. The field
ZZZZZ specifies the optimization algorithm, which can be one of `dense',
`gmres', `bicgs', or `tfqmr', following the names used by the API for
`kinsol' in C. The field Y determines the way gradients are obtained,
which is either `j' for a user supplied Jacobian, or `d' for finite
differences computed by `kinsol'. The remaining field X is either `c'
for constrained optimization, or `u' for unconstrained. Hence, the
whole function name can be one of sixteen possible alternatives.

     cd_dense   cd_gmres   cd_bicgs   cd_tfqmr
     ud_dense   ud_gmres   ud_bicgs   ud_tfqmr
     cj_dense   cj_gmres   cj_bicgs   cj_tfqmr
     uj_dense   uj_gmres   uj_bicgs   uj_tfqmr

   More specific information about the optimization algorithms can be
found in the `kinsol' documentation at the above address. Different
algorithms may perform better on different problems.

* Menu:

* kinsol input parameters::
* kinsol output::
* kinsol exceptions::
* Additional kinsol notes::


File: avram.info,  Node: kinsol input parameters,  Next: kinsol output,  Prev: kinsol,  Up: kinsol

D.9.1 `kinsol' input parameters
-------------------------------

Functions whose names are of the form `Xd_ZZZZZ' take an argument of
the form `(F,(I,O))', and functions whose names are of the form
`Xj_ZZZZZ' take an argument of the form `((F,J),(I,O))'.  The
parameters have these interpretations.

   * F is a function to be optimized, expressed in virtual machine
     code. It takes a list of real numbers as input and returns a list
     of real numbers as output. The numbers must be in floating point
     format as described in *note math::.

   * J is a function in virtual machine code that computes the Jacobian
     or partial derivatives of F for a given list of input numbers. The
     exact calling convention for J depends on the optimization
     algorithm selected, as explained below.

   * I is a list of real numbers suitable as an input for F.  The exact
     values of the numbers in I are not crucial but the length of I is
     taken as an indication of the required length for any input list
     to F. In the case of constrained optimization problems (i.e.,
     functions with names beginning with `c'), I must consist entirely
     of non-negative numbers.

   * O is a list numbers indicating the "optimal" output from F in the
     sense described below (*note kinsol output::). Its length is taken
     to indicate the usual length of an output returned by F.

   If the optimization problem is being solved by either the `cj_dense'
or the `uj_dense' method, the Jacobian parameter J is expected to take
a list V of real numbers the length of I as input and return a list of
lists of reals as output. The numbers are represented as described in
*note math::. The outer list in the output from J is required to be the
length of O, while each inner list is required to be the length of I.

   The output from J is interpreted as a matrix of the form described
in *note Two dimensional arrays::. The entry in row M and column N is
the partial derivative (evaluated at V) of the M-th component of the
output of F with respect to the N-th item of the input list.

   For optimization problems being solved by the methods of `Xj_gmres',
`Xj_bicgs', or `Xj_tfqmr', (i.e., where X is either `c' or `u') the
Jacobian function J follows a different convention that is meant to be
more memory efficient. Given an argument of the form `(M,V)', it
returns only the M-th row of the matrix described above instead of the
whole thing. The parameter M is a natural number less than the length
of O, and V is a list of real numbers the length of I the same as
above. The number M is encoded as described in *note Representation of
Numeric and Textual Data::.


File: avram.info,  Node: kinsol output,  Next: kinsol exceptions,  Prev: kinsol input parameters,  Up: kinsol

D.9.2 `kinsol' output
---------------------

The `kinsol' functions attempt to search the domain of F for a vector V
the length of I to satisfy `F(V) = O' as closely as possible. In the
case of constrained optimization, (i.e., functions whose names begin
with `c'), only non-negative numbers are acceptable in V. The search
for V will start in the vicinity of I. The value of I will therefore
determine a unique solution if multiple solutions exist, and will save
time if it is near a solution.

   In some cases when a solution can't be found due to non-convergence, an
empty list is returned. Non-convergence is not considered an
exceptional condition. In all other cases where no exception occurs,
the output from a `kinsol' function will be the list V of real numbers
satisfying `F(V) = O' to the best possible tolerance.  


File: avram.info,  Node: kinsol exceptions,  Next: Additional kinsol notes,  Prev: kinsol output,  Up: kinsol

D.9.3 `kinsol' exceptions
-------------------------

   * Any error messages that may be generated in the course of
     evaluating the functions F and J will propagate to the result
     returned by the `kinsol' library functions.

   * If there is insufficient memory to complete any operation, the
     result is a message of

          <'memory overflow'>

   * If the argument to the library function (i.e., `(F,(I,O))' or
     `((F,J),(I,O))') fails to meet the required specifications in a
     detectable way, the result will be a message of 

          <'bad kinsol specification'>

   * Any status returned by any `kinsol' API functions other than
     success or one of several types of non-convergence results in a
     message of

          <'kinsol error'>


File: avram.info,  Node: Additional kinsol notes,  Prev: kinsol exceptions,  Up: kinsol

D.9.4 Additional `kinsol' notes
-------------------------------

When a user supplied Jacobian function J is specified, the solution is
likely to be found faster and more accurately. The Jacobian should be
given if an analytical form for F is known, from which the Jacobian can
be obtained easily by partial differentiation. If the Jacobian is
unavailable, a finite difference method implemented internally by
`kinsol' is used as a substitute and will usually yield acceptable
results.

   Tolerances are not explicitly specified on the virtual side of the
interface although the native `kinsol' API requires them. A range of
tolerances over ten orders of magnitude is automatically tried before
giving up.

   Similarly to the `glpk' and `lpsolve' library interfaces (*note
glpk:: and *note lpsolve::), the only expressible constraint through the
virtual code interface is that all variables are non-negative.
Arbitrary upper and lower bounds can be simulated by appropriate
variable substitutions in the formulation of the problem.

   The `kinsol' library natively requires a system function F with
equally many inputs as outputs, and will search only for the input
associated with an output vector of all zeros, but the virtual code
interface relaxes these requirements by allowing a function that
transforms between lists of unequal lengths, and will search for the
input of F causing it to match any given "optimal" output O. These
effects are achieved by padding the shorter of the two vectors
transparently and subtracting the specified optimum from the result.

   The `kinsol' library can be configured to use single precision,
double precision, or extended precision arithmetic, but only a double
precision configuration is compatible with `avram'. This condition is
checked when `avram' is configured and it will not interface with
alternative `kinsol' configurations.

   The `kinsol' library has some more advanced features to which this
interface doesn't do justice, such as preconditioning, scaling,
solution of systems with band limited Jacobians, and concurrent
computation.


File: avram.info,  Node: lapack,  Next: math,  Prev: kinsol,  Up: External Libraries

D.10 `lapack'
=============

An arsenal of weapons grade linear algebra functions from the `LAPACK'
Fortran library is accessible to virtual code applications through
library calls of the form

     library('lapack',f)

   Each library function `f' invokes a `LAPACK' function of the same
name, but the calling conventions on the virtual side are an artifact
of the interface requiring their own documentation.

   Some functions that are part of `LAPACK' are not described here
(mostly the so called computational and auxiliary routines, and anything
in single precision), because they are not accessible by the virtual
code interface.

* Menu:

* lapack calling conventions::
* lapack exceptions::
* Additional lapack notes::


File: avram.info,  Node: lapack calling conventions,  Next: lapack exceptions,  Prev: lapack,  Up: lapack

D.10.1 `lapack' calling conventions
-----------------------------------

A table describing the inputs and outputs to the `lapack' library
functions listed by their function names is given in this section. Some
general points related to most of the functions are mentioned first.

   * References to vectors, matrices, and packed matrices should be
     understood as their list representations explained in *note Type
     Conversions::. Although `LAPACK' internally uses column order
     arrays, the virtual code library interface exhibits a matrix as a
     list of lists with one inner list for each row.

   * Some functions require a symmetric matrix as an input parameter.
     Any input parameter that is required to be a symmetric matrix may
     be specified optionally either in square form or in triangular
     form as described in *note Two dimensional arrays::. If a square
     matrix form is used, symmetry is not checked and the lower
     triangular portion is ignored.

   * Some function names are listed in pairs differing only in the first
     letter.  Function names beginning with `d' pertain to vectors or
     matrices of real numbers (*note math::), and function names
     beginning with `z' pertain to complex numbers (*note complex::).
     The specifications of similarly named functions are otherwise
     identical.

`dgesvx'

`zgesvx'
     These library functions take a pair `(A,B)' where A is an N by N
     matrix and B is a vector of length N. If A is non-singular, they
     return a vector X such that `A X = B'.  Otherwise they return an
     empty list.

`dgelsd'

`zgelsd'
     These functions generalize those above by taking a pair `(A,B)'
     where A is an M by N matrix and B is a vector of length M, with M
     greater than N. They return a vector X of length N to minimize the
     magnitude of `B - A X'.

`dgesdd'

`zgesdd'
     These functions take a list of M time series (i.e., vectors) each
     of length N and return a list of basis vectors each of length N.
     The basis vectors span the set of time series in the given list
     according to the singular value decomposition (i.e., with the
     basis vectors forming a series in order of decreasing
     significance). The number of basis vectors is at most `MIN(M,N)'
     but could be less if the input time series aren't linearly
     independent. An empty list could be returned due to lack of
     convergence.

`dgeevx'

`zgeevx'
     These functions take a non-symmetric square matrix and return a
     pair `(E,V)' where E is a list of eigenvectors and V is a list of
     eigenvalues, both of which will contain only complex numbers.
     (N.B., both functions return complex results even though `dgeevx'
     takes real input.) They could also return `nil' due to a lack of
     convergence.

`dpptrf'

`zpptrf'
     These functions take a symmetric square matrix and return one of
     the Cholesky factors. The Cholesky factors are a pair of
     triangular matrices, each equal to the transpose of the other,
     whose product is the original matrix.

        * If the input matrix is specified in lower triangular form,
          the lower triangular Cholesky factor is returned.

        * If the input matrix is specified in square or upper
          triangular form, the upper triangular Cholesky factor is
          returned.

        * In either case, the result is returned in triangular form.

`dggglm'

`zggglm'
     The input is a pair of matrices and a vector `((A,B),D)'. The
     output is a pair of vectors `(X,Y)' satisfying `AX + BY = D' for
     which the magnitude of Y is minimal. The dimensions all have to be
     consistent, which means the number of rows in A and B is the
     length of D, the number of columns in A is the length of X, and
     the number of columns in B is the length of Y.

`dgglse'

`zgglse'
     The input is of the form `((A,C),(B,D))' where A and B are
     matrices and C and D are vectors. The output is a vector X to
     minimize the magnitude of `AX - C' subject to the constraint that
     `BX = D'. The dimensions have to be consistent, which means A has
     M rows, C has length M, B has P rows, D has length P, both A and B
     have N columns, and the output X has length N. It is also a
     requirement that `P <= N <= M + P'.

`dsyevr'
     This function takes a symmetric real matrix and returns a pair
     `(E,V)' where E is a list of eigenvectors and V is a list of
     eigenvalues. Both contain only real numbers.  This function is
     fast and accurate but not as storage efficient as possible. If
     there is insufficient memory, it automatically invokes `dspev'.

`dspev'
     This function takes a symmetric real matrix and returns a pair
     `(E,V)' where E is a list of eigenvectors and V is a list of
     eigenvalues. Both contain only real numbers.  It uses roughly half
     the memory of `dsyevr' but is not as fast or accurate.

`zheevr'
     This function takes a complex Hermitian matrix and returns a pair `(E,V)'
     where E is a list of eigenvectors and V is a list of eigenvalues.
     The eigenvectors are complex but the eigenvalues are real.

        * A Hermitian matrix has AIJ equal to the complex conjugate of
          AJI.

        * Although not exactly symmetric, a Hermitian matrix may
          nevertheless be given in either upper or lower triangular
          form.

        * This function is faster but less storage efficient than
          `zhpev', and calls it automatically if it runs out of memory.

`zhpev'
     This function has the same inputs and approximate outputs as
     `zheevr' but is slower and more memory efficient because it uses
     only packed matrices.


File: avram.info,  Node: lapack exceptions,  Next: Additional lapack notes,  Prev: lapack calling conventions,  Up: lapack

D.10.2 `lapack' exceptions
--------------------------

   * Any of these functions can return a message of

          <'memory overflow'>

     if it runs out of memory.

   * If the input parameters don't meet the specification, they can
     also return 

          <'bad lapack specification'>

   * Any unexpected behavior from the `LAPACK' Fortran functions or
     irregular status returned by them is reported by the message 

          <'lapack error'>

     Getting to the bottom of it may require some debugging of the
     `avram' source code in the file `lapack.c'.


File: avram.info,  Node: Additional lapack notes,  Prev: lapack exceptions,  Up: lapack

D.10.3 Additional `lapack' notes
--------------------------------

The functions `dgesdd' and `zgesdd' are an effective dimensionality
reduction technique for a large database of time series.  A set of
basis vectors can be computed once for the database, and then any time
series in the database can be expressed as a linear combination
thereof. To the extent that the data embody any redundant information,
an approximate reconstruction of an individual series from the database
will require fewer coefficients (maybe far fewer) in terms of the basis
than original length of the series.

   The library functions `dgelsd' and `zgelsd' are good for finding
least squares fits to empirical data. If the matrix parameter A is
interpreted as a list of inputs and the vector parameter B as the list
of corresponding output data from some unknown linear function of N
variables F, then X is the list of coefficients whereby F achieves the
optimum fit to the data in the least squares sense.

   These functions solve a special case of the problem solved by `dggglm'
and `zggglm' where the parameter B is the identity matrix. For the
latter functions, the output vector Y can be interpreted as a measure
of the error, and B can be chosen to express unequal costs for errors
at different points in the fitted function.

   Cholesky decompositions obtained by `dpptrf' and `zpptrf' are useful
for generating correlated random numbers. A population of vectors of
uncorrelated standard normally distributed random numbers can be made
to exhibit any correlations to order by multiplying all of the vectors
by the lower Cholesky factor of the desired covariance matrix.


File: avram.info,  Node: math,  Next: mtwist,  Prev: lapack,  Up: External Libraries

D.11 `math'
===========

The `math' library exports functions that operate on IEEE double
precision floating point numbers using the host system's C library. The
numbers are represented natively as contiguous blocks of 8 bytes each,
and on the virtual side as lists of eight character representations.
(More explanation is given in *note Type Conversions::.) These
functions take the form

     library('math',f)

where `f' is a character string identifying the function in most cases
by its standard name in the C library.

* Menu:

* math library operators::
* math library predicates::
* math library conversion functions::
* math library exceptions::
* Additional math library notes::


File: avram.info,  Node: math library operators,  Next: math library predicates,  Prev: math,  Up: math

D.11.1 `math' library operators
-------------------------------

The unary operators take a single real number to a real result. They include

     ceil  floor round trunc
     sin   cos   tan   sinh   cosh   tanh
     asin  acos  atan  asinh  acosh  atanh
     exp   log   sqrt  cbrt   expm1  log1p  fabs

   The binary operators take a pair of real numbers `(X,Y)' to a single
real number output. They include

     pow  hypot  atan2  remainder  bus  vid  add  sub  mul  div

where the last four correspond to the C language operators `+', `-',
`*', and `/'. The functions named `bus' and `vid' are like the `sub'
and `div' functions, respectively, with the order of the operands
reversed, as explained in *note complex::.

   The meanings of these operators are documented in the GNU `libc'
reference manual or other C language references. They follow IEEE
standards including proper handling of `nan' and infinity.


File: avram.info,  Node: math library predicates,  Next: math library conversion functions,  Prev: math library operators,  Up: math

D.11.2 `math' library predicates
--------------------------------

There is one binary predicate, `islessequal', and several unary predicates,
`isinfinite', `isnan', `isnormal', `isubnormal' and `iszero'.

   The predicate `islessequal' takes a pair of floating point numbers
`(X,Y)' as an argument, and returns `nil' for a false result and
`(nil,nil)' for a true result.

   The unary predicates have the obvious interpretations as
classification functions, and should probably be used in preference to
comparison with constants in case the representations aren't unique.


File: avram.info,  Node: math library conversion functions,  Next: math library exceptions,  Prev: math library predicates,  Up: math

D.11.3 `math' library conversion functions
------------------------------------------

The conversion function `strtod' takes a string representing a floating
point number in C format to its representation. This function is the
primary means of creating or initializing floating point numbers in
virtual code. A value of floating point 0.0 is returned if the string
is not valid, but no exception is raised.

   The conversion `asprintf' is similar to the one by that name in C,
but requires a pair `(F,X)' as an argument.  The left side F is a
character string containing a C style format conversion for exactly one
double precision floating point number, such as `'%0.4e'', and the
parameter X is a floating point number. The result returned will be a
character string expressing the number in the specified format.


File: avram.info,  Node: math library exceptions,  Next: Additional math library notes,  Prev: math library conversion functions,  Up: math

D.11.4 `math' library exceptions
--------------------------------

The most likely cause of an exception is an attempt to apply a `math'
library function to `nil' or to an argument that doesn't represent a
floating point number. In these cases, an error message of `<'missing
value'>' or `<'invalid value'>' will be the result.

   An error message of `<'invalid asprintf() specifier'>' is reported
by the `asprintf' function if the format specifier pertains to a
string, such as `'%s''. This error is specifically trapped because the
alternative would be a segmentation fault. Otherwise, invalid format
specifiers are not detected or reported.

   Error messages of `<'invalid text format'>' can be generated by
conversion functions if any parameters that are meant to be character
string representations are something else.

   There is always a chance of a `<'memory overflow'>' error if there
is insufficient memory to allocate a result.


File: avram.info,  Node: Additional math library notes,  Prev: math library exceptions,  Up: math

D.11.5 Additional `math' library notes
--------------------------------------

Floating point exceptions such as division by zero are not specifically
reported as exceptions, but invalid computations can be detected by the
propagation of `nan' into the result, following standard conventions.

   The C function `feclearexcept (FE_ALL_EXCEPT)' is called before every
floating point operation so that no lingering exception flags can
affect it.

   There is no library predicate for exact comparison of floating point
numbers, but none is required because the virtual machine's `compare'
combinator will work on their representations as it will on any other
data. The usual caveats apply with regard to comparing floating point
numbers in the presence of roundoff error.


File: avram.info,  Node: mtwist,  Next: minpack,  Prev: math,  Up: External Libraries

D.12 `mtwist'
=============

The `mtwist' library interfaces to a random number generator based on
the Mersenne Twistor algorithm. The algorithm has good properties but
is not meant to be cryptographically secure. The library functions are
of the form

     library('mtwist',f)

where `f' is one of the followng character strings.

     bern   u_cont   u_disc   u_path   u_enum   w_disc   w_enum

   Formally they are not mathematical functions because their results
depend on a pseudo-random number that is not uniquely determined by
their arguments. The numbers are generated deterministically in a
sequence starting from a seed derived from the system clock at the time
`avram' is launched, and each call uses the next number in the
sequence. In so doing, it simulates a random draw from a uniformly
distributed population.

* Menu:

* mtwist calling conventions::
* mtwist exceptions::
* Additional mtwist notes::


File: avram.info,  Node: mtwist calling conventions,  Next: mtwist exceptions,  Prev: mtwist,  Up: mtwist

D.12.1 `mtwist' calling conventions
-----------------------------------

All of the functions in this library simulate a random draw from a
distribution. There is a choice of distribution statistics depending on
the function used.

`bern'
     takes a floating point number P between 0 and 1, encoded as in
     *note math::, and returns a boolean value, either `(nil,nil)' for
     true or `nil' for false. A true value is returned only if a random
     draw from a uniform distribution ranging from 0 to 1 is less than
     P.  This function therefore simulates a draw from a Bernoulli
     distribution. A `nil' value of P is treated as 1/2.

`u_cont'
     takes a floating point number X as an argument, and returns a
     random draw from a continuous uniform distribution ranging from 0
     to X. A `nil' value of X is treated as unity.

`u_disc'
     simulates a draw from a uniform discrete distribution whose domain
     is the set of natural numbers from 0 to N - 1. The number N is
     given as a parameter to this function, and the retuned value is
     the draw.

        * The returned value will have at most 64 bits regardless of N.

        * Natural numbers are encoded as described in *note
          Representation of Numeric and Textual Data::.

        * If a value of 0 is passed for N, the full 64 bit range is
          used.

`u_path'
     takes a pair of natural numbers `(N,M)' and returns a randomly
     chosen tree (*note Raw Material::) with 1 leaf and N non-leaves
     each having either a left or a right descendent but not both. The
     number M constrains the result to fall within the first M - 1
     trees of this form enumerated by exhausting all possibilities at
     lower levels before admitting a right descendent at a higher
     level. Within these criteria, all possible results are equally
     probable. Both numbers are masked to 64 bits, but if M is zero, it
     is treated as 2^N.

`u_enum'
     simulates a random draw from a uniform discrete distribution whose
     domain is enumerated. The argument to the function is a non-empty
     list, and the result is an item selected from the list, with all
     choices being equally probable.

`w_disc'
     simulates a random draw from a non-uniform, or "weighted" discrete
     distribution whose domain is a set of consecutive natural numbers
     starting from zero. The argument to the function is a list giving
     the probability of each outcome starting from zero as a floating
     point number. Probabilities must be non-negative but needn't be
     normalized.

`w_enum'
     simulates a random draw from a non-uniform, or "weighted" discrete
     distribution with an arbitrary domain enumerated in the argument.
     The argument is a list of pairs `<(X,P)..>', where X is a possible
     outcome and P is its probability. The result returned is one of
     the values of X from the input list chosen at random according to
     the associated probability. Probabilities must be non-negative but
     needn't be normalized.


File: avram.info,  Node: mtwist exceptions,  Next: Additional mtwist notes,  Prev: mtwist calling conventions,  Up: mtwist

D.12.2 `mtwist' exceptions
--------------------------

   * `<'memory overflow'>' can be returned if there is insufficient
     memory to allocate a result.

   * Messages of `<'missing value'>' and `<'invalid value'>' can be
     returned if any floating point argument is `nil' or is not a valid
     floating point number, unless there is a designated default
     interpretation for `nil' as in `bern' and `u_cont'.

   * A message of `<'bad mtwist specification'>' is returned if an
     argument to the `bern' function is not in the range of 0 to 1, or
     if any probability passed to the `w_'* functions is negative.

   * A message of `<'draw from empty list'>' is returned if an argument
     to the *`_enum' functions is `nil' or if an argument to `w_enum'
     contains `nil'.


File: avram.info,  Node: Additional mtwist notes,  Prev: mtwist exceptions,  Up: mtwist

D.12.3 Additional `mtwist' notes
--------------------------------

Although the `mtwist' library is "external", it requires no special
configuration on the host because the uniform variate generator in the
form developed by its original authors is short and elegant enough to
be packaged easily within the `avram' distribution. All further
embellishments are home grown despite the advice at the end of *note
Implementing new library functions::.

   The `u_path' function is intended to allow sampling from a large
population in logarithmic time when it is stored in a balanced tree. A
left-heavy tree should be constructed initially with the data items all
at the same level. Thereafter, a result returned by `u_path' with the
appropriate dimensions can be used as an index into the tree for fast
retrieval by the virtual machine's `field' combinator (*note Field::).

   The last three functions, `u_enum', `w_disc', and `w_enum' use an
inversion method with a binary search.  The first draw from a given
list will take a time asymptotically proportional to the length of the
list, but subsequent draws from the same list are considerably faster
due to a persistent cache maintained transparently by `avram'. For
lists whose length is up to 2^16, the time required for a subsequent
draw consists mainly of constant overhead with a small logarithmic
component in the length of the list. For longer lists, the time ramps
up linearly by a small factor.

   Information allowing fast draws from up to sixteen lists can be
cached simultaneously. If an application uses more than sixteen, the
cached data are replaced in first-in first-out order. The size of the
cache and the maximum list length for logarithmic time access can be
adjusted easily by redefining constants in `mtwist.c' under the `avram'
source tree, but will require recompilation.


File: avram.info,  Node: minpack,  Next: mpfr,  Prev: mtwist,  Up: External Libraries

D.13 `minpack'
==============

The `minpack' library contains functions to solve non-linear optimization
and least squares problems. The functions can be expressed as

     library('minpack',f)

where `f' can be one of `'hybrd'', `'hybrj'', `'lmder'', `'lmdif'', or
`'lmstr'', following the names of the underlying Fortran subroutines.

* Menu:

* minpack calling conventions::
* minpack exceptions::
* Additional minpack notes::


File: avram.info,  Node: minpack calling conventions,  Next: minpack exceptions,  Prev: minpack,  Up: minpack

D.13.1 `minpack' calling conventions
------------------------------------

The `minpack' library solves a similar problem to that of the `kinsol'
library (*note kinsol::), and the two libraries have identical calling
conventions at the level of the virtual code interface.

   The `hybrd' and `lmdif' functions take input arguments of the form
`(F,(I,O))', whereas `hybrj', `lmder', and `lmstr' take arguments of
the form `((F,J),(I,O))'.  The interpretations of these parameters are
explained in *note kinsol input parameters::.

   For the `lmstr' function, the Jacobian function J takes an argument
`(M,V)' and returns only the M-th row of the Jacobian matrix. For
`lmder' and `hybrj', the Jacobian function takes only an input vector V
and returns the whole matrix. These specifications are also explained
further in relation to the `kinsol' library.

   The output from any minpack function is a vector V satisfying `F(V)
= O' to the best possible tolerance if a solution is found. A range of
tolerances over ten orders of magnitude is sampled starting from
`1e-15'. If no solution is found, an empty list is returned.


File: avram.info,  Node: minpack exceptions,  Next: Additional minpack notes,  Prev: minpack calling conventions,  Up: minpack

D.13.2 `minpack' exceptions
---------------------------

   * A message of `<'memory overflow'>' is possible any time `minpack'
     runs out of memory.

   * A message of `<'bad minpack specification'>' will be returned if
     an input argument recognizably violates the required specification.

   * The `<'minpack error'>' message is returned in the event of any unexpected
     behavior or irregular status from the API.

   * Any error messages reported by the system function F or the
     Jacobian function J are propagated to the result.


File: avram.info,  Node: Additional minpack notes,  Prev: minpack exceptions,  Up: minpack

D.13.3 Additional `minpack' notes
---------------------------------

The `lm'* functions are better suited to problems in which the system
function F has more outputs than inputs, and the `hybr'* functions are
better suited to the alternative. If either is called when the other is
more appropriate, the job is handed off to the other automatically.

   The `lmstr' function is more memory efficient than the others
because it doesn't compute the whole Jacobian matrix at once. Any of
the `lm'* functions is more memory efficient than the `kinsol'
equivalent when the output list is sufficiently longer than the input
list.

   Unlike `kinsol', there is no provision in `minpack' for constrained
optimization.

   The `minpack' documentation doesn't state whether it's re-entrant,
but the odds are against it unless it uses no storage outside the user
provided work areas. If it isn't re-entrant, anomalous effects could
occur when a virtual code function being optimized calls another
`minpack' function.  A workaround would be to use an equivalent
`kinsol' function, which is re-entrant by design.

   The `avram' configuration script searches for a C header file `minpack.h'
on the host system in order to build an interface to this library. This
file is specific to the Debian `minpack-dev' package and is not part of
the upstream Fortran source. Configuring `avram' with an interface to
the `minpack' library on a non-Debian system may require the
administrator to retrieve the header file manually from the Debian
archive and place it under `/usr/include' before running the
configuration script (in addition to installing the `minpack' library
itself, of course).


File: avram.info,  Node: mpfr,  Next: lpsolve,  Prev: minpack,  Up: External Libraries

D.14 `mpfr'
===========

The `mpfr' library provides a rich assortment of floating point
operations on arbitrary precision numbers (`http://www.mpfr.org').
These numbers are represented in a format that is not binary compatible
with the standard IEEE floating point number format used by other
libraries, but they offer superior numerical stability suitable for
many ill conditioned problems.

   The virtual code interface to the `mpfr' library follows the native
API to the extent of using the same names for most operations, but
excludes features pertaining to i/o, mutable storage, and memory
management.

   The `mpfr' library functions are invoked by an expression of the form

     library('mpfr',f)

Aside from a few exceptions as noted, `f' is a character string derived
from the name of the related function from the `mpfr' C library as
documented at the above address, but without the `mpfr_' prefix.

   The full complement of available functions is documented in the
remainder of this section.

   * References to natural numbers pertain to the list representation
     described in *note Representation of Numeric and Textual Data::.

   * All functions that perform rounding use a mode of `GMP_RNDN' for rounding
     to nearest, which is not explicitly specified on the virtual side.

* Menu:

* mpfr binary operators::
* mpfr unary operators::
* mpfr binary operators with a natural operand::
* mpfr binary predicates::
* mpfr unary predicates::
* mpfr constants::
* mpfr functions with miscellaneous calling conventions::
* mpfr conversion functions::
* mpfr exceptions::
* Additional mpfr notes::


File: avram.info,  Node: mpfr binary operators,  Next: mpfr unary operators,  Prev: mpfr,  Up: mpfr

D.14.1 `mpfr' binary operators
------------------------------

Functions with these names take a pair of `mpfr' numbers `(X,Y)' and
return an `mpfr' number as a result.

   * `add'

   * `sub'

   * `mul'

   * `div'

   * `pow'

   * `atan2'

   * `hypot'

   * `min'

   * `max'

   * `vid'

   * `bus'

   Their semantics are similar to those listed in the `mpfr'
documentation, with some minor qualifications.

   * Unlike the native API, there is no third argument to which the
     result is assigned, because the result is the returned value.

   * The precision of the result is the greater of the two precisions of
     the input numbers X and Y.

   * The `vid' and `bus' functions are added features of the virtual
     code interface, corresponding to division and subtraction with the
     order of the operands reversed, as explained in *note complex::.

   Mathematically it might make more sense for the precision of the result
to be the lesser of the two input precisions, but this way is more
convenient for virtual code programs that perform binary operations on
their input with hard coded constants, because it makes one size fit
all.


File: avram.info,  Node: mpfr unary operators,  Next: mpfr binary operators with a natural operand,  Prev: mpfr binary operators,  Up: mpfr

D.14.2 `mpfr' unary operators
-----------------------------

Functions with these names take a single `mpfr' number as an argument
and return a single `mpfr' number as a result.  

     sqr      sqrt     cbrt     neg      abs      log
     log2     log10    exp      exp2     exp10    cos
     sin      tan      acos     asin     atan     cosh
     sinh     tanh     acosh    asinh    atanh    lngamma
     expm1    eint     gamma    erf      log1p    nextbelow
     ceil     floor    round    trunc    frac     nextabove
     erfc

   The semantics of these functions are similar to those of their
counterparts in the native API, with these provisions.

   * The precision of the result is the precision of the argument.

   * There is no second argument for assigning the result.

   * The `nextabove' and `nextbelow' functions do not modify their
     arguments in place, but return a freshly allocated result like all
     other functions.


File: avram.info,  Node: mpfr binary operators with a natural operand,  Next: mpfr binary predicates,  Prev: mpfr unary operators,  Up: mpfr

D.14.3 `mpfr' binary operators with a natural operand
-----------------------------------------------------

Functions with these names take an argument of the form `(X,N)', where
X is an `mpfr' number and N is a natural number.

   * `root'

   * `pow_ui'

   * `mul_2ui'

   * `div_2ui'

   * `grow'

   * `shrink'

   The last two are specific to the virtual code interface, having no
counterpart in the native API of the `mpfr' library.  The `grow'
function returns a copy of X with its precision increased by N bits,
and the `shrink' function returns a copy of X with its precision
reduced by N bits.

   * The precisions are silently capped at the maximum or floored at the minimum
     allowable precisions if necessary.

   * Increasing the precision by the `grow' function does not directly
     cause a more accurate result to be computed, but only pads an
     existing number with zeros.

   * Decreasing the precision by the `shrink' function does not prevent
     valid bits from being discarded.

   The appropriate way to use `grow' is to grow the precision of an
operand before applying an operator to it, which will cause the result
to be computed to the full precision. This capability is suitable for
algorithms that iterate over increasing precisions until a stopping
criterion is met.


File: avram.info,  Node: mpfr binary predicates,  Next: mpfr unary predicates,  Prev: mpfr binary operators with a natural operand,  Up: mpfr

D.14.4 `mpfr' binary predicates
-------------------------------

These predicates take a pair of `mpfr' numbers `(X,Y)' as arguments and
perform a logical operation.  If the result is true, they return
`(nil,nil)', and if it's false, they return `nil'.

   * `equal_p'

   * `unequal_abs'

   * `greater_p'

   * `greaterequal_p'

   * `less_p'

   * `lessequal_p'

   * `lessgreater_p'

   The name of the function `unequal_abs', for comparing absolute
values, has been changed from `mpfr_cmpabs' to avoid confusion with the
virtual machine's `compare' combinator. The `compare' combinator
returns a `(nil,nil)' result (i.e., true) if the operands are equal and
a `nil' result if they're unequal, opposite from `unequal_abs'.


File: avram.info,  Node: mpfr unary predicates,  Next: mpfr constants,  Prev: mpfr binary predicates,  Up: mpfr

D.14.5 `mpfr' unary predicates
------------------------------

Each of these predicates takes an `mpfr' number as an argument and
performs a logical operation. If the result is true, it returns
`(nil,nil)', and otherwise it returns `nil'.

   * `nan_p'

   * `inf_p'

   * `number_p'

   * `zero_p'

   * `integer_p'


File: avram.info,  Node: mpfr constants,  Next: mpfr functions with miscellaneous calling conventions,  Prev: mpfr unary predicates,  Up: mpfr

D.14.6 `mpfr' constants
-----------------------

Each of these functions takes a natural number as an argument
specifying a precision, and returns a mathematical constant evaluated
to that precision.

   * `const_log2'

   * `pi'

   * `const_catalan'

   * `inf'

   * `ninf'

   * `nan'

   The name of the constant `pi' has been shortened from
`mpfr_const_pi'.  The functions `inf' and `ninf' return infinity and
negative infinity, respectively.

   The encoding of `nan', used to represent the results of undefined computations
such as division by zero, is not unique even for a fixed precision.
Applications should test for undefined results using `nan_p' rather
than by comparing a result to a hard coded `nan' (*note mpfr unary
predicates::).


File: avram.info,  Node: mpfr functions with miscellaneous calling conventions,  Next: mpfr conversion functions,  Prev: mpfr constants,  Up: mpfr

D.14.7 `mpfr' functions with miscellaneous calling conventions
--------------------------------------------------------------

Some functions listed below don't conform to any of the previously
mentioned calling conventions.

`eq'
     This is a ternary operator taking a triple `(PREC,(X,Y))', where
     PREC is a natural number and X and Y are `mpfr' numbers. It
     returns a result of `(nil,nil)' (i.e., true) if the numbers agree
     up to the specified precision measured in bits, and returns `nil'
     otherwise.(1)

`urandomb'
     This function takes a natural number specifying a precision and returns
     a uniformly distributed pseudo-random number of that precision
     between 0 and 1.

`prec'
     This function takes an `mpfr' number and returns a natural number
     as a result, which is the precision of the argument in bits.

`sin_cos'
     This function takes an `mpfr' number Z as an argument and returns
     a pair of `mpfr' numbers `(X,Y)' as a result, where X is the sine
     of Z and Y is the cosine.  The precisions of the results are the
     same as the precision of the argument.

   ---------- Footnotes ----------

   (1) a potentially useful tool for algorithms concerned with
numerical approximations despite its inexplicable malignment in the
`mpfr' documentation


File: avram.info,  Node: mpfr conversion functions,  Next: mpfr exceptions,  Prev: mpfr functions with miscellaneous calling conventions,  Up: mpfr

D.14.8 `mpfr' conversion functions
----------------------------------

The functions described in this section convert between `mpfr' numbers
and character strings, naturals, or standard IEEE floating point format
(in their list representations). Where these functions have similar or
equivalent counterparts in the `mpfr' library's native API, the names
have been changed for mnemonic reasons.

`dbl2mp'
     The input is a standard floating point number as in *note math::.
     The result is an `mpfr' number equal to the input with a fixed
     precision, currently set to 160 bits.

`mp2dbl'
     The input is an `mpfr' number, and the output is the best possible
     approximation to it by a standard a double precision number.

`str2mp'
     The input is a pair `(PREC,S)', where PREC is a natural number
     specifying the precision, and S is a string expressing a floating
     point number in C format. The output is an `mpfr' number with the
     specified precision.

`mp2str'
     The input is an `mpfr' number, and the output is a character
     string expressing the number in exponential decimal notation.
     Sufficiently many decimal digits are included in the string to
     express the full precision.

`nat2mp'
     The input is a natural number represented as described in *note
     Representation of Numeric and Textual Data::, and the output is an
     `mpfr' number of sufficient precision to express the natural
     number exactly.

   The `mp2str' function enhances the native `mpfr_get_str' function by
properly formatting the output string rather than only listing the
digits of the mantissa.

   The `nat2mp' function does not rely on the `mpfr' native integer
conversion functions, so natural numbers with any number of bits up to
`MP_PREC_MAX' can be used losslessly. There is currently no conversion
in the other direction.


File: avram.info,  Node: mpfr exceptions,  Next: Additional mpfr notes,  Prev: mpfr conversion functions,  Up: mpfr

D.14.9 `mpfr' exceptions
------------------------

   * A message of `<'memory overflow'>' is possible any time `mpfr'
     runs out of memory.

   * A message of `<'bad mpfr specification'>' will be returned if an
     input argument recognizably violates the required specification.

   * The `<'mpfr error'>' message is returned in the event of any unexpected
     behavior or irregular status from the API.

   * The message of `<'mpfr overflow'>' can be cause by the `nat2mp'
     function if a natural number has too many bits to be represented
     exactly as an `mpfr' number.


File: avram.info,  Node: Additional mpfr notes,  Prev: mpfr exceptions,  Up: mpfr

D.14.10 Additional `mpfr' notes
-------------------------------

The `eq' and `urandomb' functions depend not only on the `mpfr' library
but on the `gmp' library (`http://ftp.gnu.org/gnu/gmp'). It's possible
for them to be unavailable on a host without `gmp' even if the rest of
the `mpfr' library is properly configured.

   The file `mpfr.c' in the `avram' source tree exports a couple of
functions that may be of use to C hackers interested in further
development of `avram' with `mpfr'. The functions `avm_mpfr_of_list'
and `avm_list_of_mpfr' convert between the native representation for
`mpfr' numbers and the caching list representation used by `avram'
(*note Type Conversions::). This conversion is non-trivial because the
numbers are not stored contiguously.


File: avram.info,  Node: lpsolve,  Next: rmath,  Prev: mpfr,  Up: External Libraries

D.15 `lpsolve'
==============

This library interface exports functions to solve linear programming and
mixed integer programming problems using the `lpsolve' package
documented at

   `http://lpsolve.sourceforge.net/5.5/'.

Of the two linear programming solvers currently interfaced with
`avram', this one is believed to be the more robust.

* Menu:

* lpsolve calling conventions::
* lpsolve return values::
* lpsolve errors::


File: avram.info,  Node: lpsolve calling conventions,  Next: lpsolve return values,  Prev: lpsolve,  Up: lpsolve

D.15.1 `lpsolve' calling conventions
------------------------------------

The library is able to solve linear and mixed integer programming
problems, depending on which function is selected. The function to call
the linear programming solver is of the form

   * `library('lpsolve','stdform')'

and the mixed integer programming functions are of the form

   * `library('lpsolve','iform')'

   * `library('lpsolve','bform')'

   * `library('lpsolve','biform')'

The argument to the `stdform' function represents a triple `(C,(M,Y))',
which has the same interpretation described in *note glpk input
parameters::. The arguments to the `iform', `bform', and `biform'
functions are tuples `(I,(C,(M,Y)))' `(B,(C,(M,Y)))', and
`((B,I),(C,(M,Y)))', respectively, where C, M, and Y are as above, and

   * B is a list of binary variable column indices

   * I is a list of integer variable column indices

where column indices pertain to the constraint matrix, and are numbered
from zero.  Specifying some or all variables as integers directs the
solver to seek only solutions in which those variables have integer
values, and specifying any as binary directs the solver to seek only
solutions in which those variables have values of zero or one.  The
IEEE floating point representation is used for all variables regardless
(*note math::).


File: avram.info,  Node: lpsolve return values,  Next: lpsolve errors,  Prev: lpsolve calling conventions,  Up: lpsolve

D.15.2 `lpsolve' return values
------------------------------

If a feasible and optimal solution is found, a list of values for the
variables is returned in the form `<(I,X)...>', where I is a natural
number and X is a floating point number giving the value of the I-th
variable numbered from zero. Values of X equal to zero are omitted.


File: avram.info,  Node: lpsolve errors,  Prev: lpsolve return values,  Up: lpsolve

D.15.3 `lpsolve' errors
-----------------------

If any calling conventions are not followed, an exception is raised and
a diagnostic message of `bad lpsolve problem specification' is
reported. If no feasible solution can be found, no exception is raised
but an empty list is returned.


File: avram.info,  Node: rmath,  Next: umf,  Prev: lpsolve,  Up: External Libraries

D.16 `rmath'
============

A selection of mathematical and statistical functions from the GNU R
math library has a virtual code interface of the form

     library('rmath',f)

where `f' is a character string derived from the name of a function in
the C language API described in the manual `R-exts.pdf', available at
`http://www.r-project.org'.

   Every function in the library returns a real result in the form of
*note math::, but functions differ in the argument types. The arguments
are tuples of real numbers and booleans that also closely follow the
native API as explained below.

* Menu:

* rmath statistical functions::
* rmath miscellaneous functions::
* rmath exceptions::


File: avram.info,  Node: rmath statistical functions,  Next: rmath miscellaneous functions,  Prev: rmath,  Up: rmath

D.16.1 `rmath' statistical functions
------------------------------------

Functions for evaluating random draws, density, cumulative probability
and inverse cumulative probability are provided for some of the more
frequently used probability distributions, which are chi-squared,
non-central chi-squared, exponential, lognormal, normal, poisson,
Student's t, and uniform.

   Each distribution is known by an abbreviated name and specified by
one or two real parameters as listed below. Names of distributions in
this table form the stem of a library function name.  The names of the
parameters such as MU and SIGMA are not explicitly mentioned when
invoking the functions, but are listed here for reference.  The precise
definitions of the distribution functions and interpretations of these
parameters can be found in standard texts on probability and statistics.

     chisq         DF
     nchisq        DF, LAMBDA
     exp           SCALE
     lnorm         LOGMEAN, LOGSD
     norm          MU, SIGMA
     pois          LAMBDA
     t             N
     unif          A, B

   The virtual code interface follows a naming convention similar to the
native API, in that function names beginning with `r' represent random
draws from a distribution, with the argument to the function being the
parameters specifying the distribution. Functions in this first group
return a random draw from a distribution described by a single real
parameter.

   * `rchisq'

   * `rexp'

   * `rpois'

   * `rt'

These next functions return random draws from distributions specified
by a pair of parameters, `(X,Y)'.

   * `rnchisq'

   * `rlnorm'

   * `rnorm'

   * `runif'

   Functions whose names begin with `d' evaluate the probability
density of a distribution at a given point. They require at least two
real arguments, the first being the point whose probability density is
sought, and the remaining ones being the parameters that specify the
distribution. A boolean operand, which is `nil' for false and
`(nil,nil)' for true, requests the logarithm of the density when true.

   Functions with names in the following group take a triple with two
real operands and a boolean, `(X,(Y,A))', and return a probabiity
density.

   * `dchisq'

   * `dexp'

   * `dpois'

   * `dt'

The next functions pertain to distributions requiring two paramters to
specify them, so they take a quadruple with three real operands and a
boolean, `(X,(Y,(Z,A)))'.

   * `dnchisq'

   * `dlnorm'

   * `dnorm'

   * `dunif'

   Functions whose names begin with `p' or `q' obtain cumulative
probabilities or inverse cumulative probabilities respectively for a
specified distribution. They require one real operand to identify the
point whose probability or inverse probability is sought, and other
real operands to parameterize the distribution, as above. There are
also two boolean operands. The first is true in order to request a
probability or inverse probability with respect to the lower tail as
opposed to the upper, and the other is true to indicate that
probabilities are to be expressed logarithmically.

   The argument to these functions is a quadruple with two real operands
and two booleans, `(X,(Y,(A,B)))'.

   * `pchisq', `qchisq'

   * `pexp', `qexp'

   * `ppois', `qpois'

   * `pt', `qt'

The remaining functions pertain to distributions parameterized by two
real operands. These take a quintuple with three real operands and two
booleans, `(X,(Y,(Z,(A,B))))'.

   * `pnchisq', `qnchisq'

   * `plnorm', `qlnorm'

   * `pnorm', `qnorm'

   * `punif', `qunif'


File: avram.info,  Node: rmath miscellaneous functions,  Next: rmath exceptions,  Prev: rmath statistical functions,  Up: rmath

D.16.2 `rmath' miscellaneous functions
--------------------------------------

Some less frequently used real valued mathematical functions are also
accessible by the `rmath' library interface.  The functions with names
in this group take a single real operand.

     gammafn         lgammafn        digamma
     trigamma        tetragamma      pentagamma

The ones in this group take a pair of real operands `(X,Y)'.

     beta            lbeta           bessel_j       bessel_y

Those remaining take a triple of real operands `(X,(Y,Z))'.

     bessel_i        bessel_k

   An alternative and better documented selection of Bessel functions is
provided by the `bes' library interface (*note bes::).


File: avram.info,  Node: rmath exceptions,  Prev: rmath miscellaneous functions,  Up: rmath

D.16.3 `rmath' exceptions
-------------------------

The only exceptional condition specific to the `rmath' library
interface is associated with the message `<'bad rmath specification'>',
which means that a tuple given as an argument has the wrong number or
types of operands.


File: avram.info,  Node: umf,  Prev: rmath,  Up: External Libraries

D.17 `umf'
==========

Systems of equations described by sparse matrices (i.e., matrices containing
mostly zeros) arise in certain practical problems. The usual array
representation in which zeros are explicitly stored would be
prohibitive for large matrices occurring in many problems of interest.
A more sophisticated approach is used by the `umf' library to manage
memory efficiently, which is documented at
`http://www.cise.ufl.edu/research/sparse/SuiteSparse/current/SuiteSparse/UMFPACK/Doc/'.

   A virtual code interface to functions for solving sparse systems of
equations by these methods is afforded by library functions of the form

     library('umf',f)

where the library function name, `f' is a character string of the form
`TT_M_RRR'.

   * TT can be either `di' for real matrices, or `zi' for complex.

   * M can be one of `a', `t', or `c' for solving a system given either
     by a matrix, its transpose, or its conjugate transpose,
     respectively, corresponding to mnemonics `A', `Aat' and `At' used
     in the C language API.

   * RRR is either `trp' or `col', to indicate a sparse matrix expressed
     either as a list of triples, or in packed column form, as
     documented below.

   The complete set of function names for this library interface is as
follows.

     di_a_trp      di_a_col       zi_a_trp       zi_a_col
     di_t_trp      di_t_col       zi_t_trp       zi_t_col
                                  zi_c_trp       zi_c_col

Not all combinations are represented, because the conjugate transpose
is relevant only to complex matrices.

* Menu:

* umf input parameters::
* umf output::
* umf exceptions::
* Additional umf notes::


File: avram.info,  Node: umf input parameters,  Next: umf output,  Prev: umf,  Up: umf

D.17.1 `umf' input parameters
-----------------------------

For a square matrix A and a column vector B, the `umf' functions find
the solution X to the matrix equation M X = B, where M is either A, the
transpose of A, or its conjugate transpose. As noted above, the choice
is determined by whether the the function name is of the form *`_a_'*,
*`_t_'*, or *`_c_'* respectively.

   The argument to any of these functions is a pair `(A,B)', where A
represents the matrix mentioned above and B represents the column
vector.

   The parameter B is required to be a list of numbers whose length
matches the number of rows in the matrix. The numbers are either real
numbers for the `di_'* functions (*note math::), or complex for the
`zi_'* functions (*note complex::).

   There is a choice of representations for the parameter A, depending
on whether the function being called is one of the *`_trp' functions or
one of the *`_col' functions.

   For the *`_trp' functions, A is represented as a non-empty list of
triples `<((I,J),V)...>', where each item of the list corresponds to a
non-zero entry in the matrix.

   * The parameters I and J are natural numbers as in *note
     Representation of Numeric and Textual Data::.

   * The value V is a real number for the `di_'*`_trp' functions or a
     complex number for the `zi_'*`_trp' functions.

   * The presence of a triple ((I,J),V) in the list signifies that the
     I,J-th entry in the matrix A (numbered from zero) has a value of V.

   For the *`_col' functions, the representation of A is more
complicated but has a slight advantage in memory usage. It may also
have an advantage in speed unless more time is wasted on the virtual
side transforming a matrix to this representation than it saves.

   In this case, A is represented by a triple of the form `((P,I),V)'.
The parameters P and I are lists of natural numbers. The parameter V is
a list of real numbers for the `di_'*`_col' functions and complex
numbers for the `zi_'*`_col' functions. They have the following
interpretations.

   * V is the list of non-zero entries in the matrix in column major
     order.

   * I has the same length as V, and each item of I is the row index of
     the corresponding item in V, numbered from zero.

   * P has the length of the number of columns in the matrix, and each
     item identifies the starting position of a column in V and I,
     numbered from zero.

The first item of P is always zero. Further explanation of this format
in terms of an array representation can be found in the file
`UMFPACK_UserGuide.pdf', available from the `umf' library home page at
`http://www.cise.ufl.edu/research/sparse/SuiteSparse/current/SuiteSparse/'.


File: avram.info,  Node: umf output,  Next: umf exceptions,  Prev: umf input parameters,  Up: umf

D.17.2 `umf' output
-------------------

If no exception occurs, the solution X to the matrix equation M X = B
noted previously will be returned if one exists.

   The solution is represented as either a list of real numbers as in
*note math::, or a list of complex numbers as in *note complex::. Real
numbers are returned by the `di_'* functions, and complex numbers are
returned by the `zi_'* functions.

   If no solution exists due to a singular matrix, an empty list is
returned. The lack of a solution isn't treated as an exceptional
condition.


File: avram.info,  Node: umf exceptions,  Next: Additional umf notes,  Prev: umf output,  Up: umf

D.17.3 `umf' exceptions
-----------------------

If an exceptional condition arises from the use of this library, one of
the following lists of character strings may be returned as the
function result.

   * `<'memory overflow'>' means the library function ran out of
     memory, most likely due to a matrix being too large.

   * `<'bad umf specification'>' means an input parameter didn't conform
     to the appropriate format described above (*note umf input
     parameters::)

   * `<'umf error'>' covers any unexpected behavior or abnormal status
     returned by any function from the C language API.

   For the *`_trp' functions. A non-square matrix will cause the second
exception above. For the *`_col' functions, a non-square matrix will
cause the third exception or cause an empty result to be returned.

   The exceptions noted at the beginning of this section (*note
External Libraries::) are also possible.


File: avram.info,  Node: Additional umf notes,  Prev: umf exceptions,  Up: umf

D.17.4 Additional `umf' notes
-----------------------------

The C language API to `umf' provides very many less frequently used
features that are not part of the virtual code interface, some of which
could be added by minor modifications to the file `umf.c' in the
`avram' source tree.

   A set of `dl_'* and `zl_'* functions orthogonal to those presently
accessible would enable matrices having billions of rows or columns by
using long integers, but memory requirements on the virtual code side
for problems of that scale are probably prohibitive for the foreseeable
future.


File: avram.info,  Node: Copying,  Next: Function Index,  Prev: External Libraries,  Up: Top

Appendix E GNU GENERAL PUBLIC LICENCE
*************************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     675 Mass Ave, Cambridge, MA 02139, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

* Menu:

* Preamble::
* Terms and Conditions::
* How to Apply::


File: avram.info,  Node: Preamble,  Next: Terms and Conditions,  Up: Copying

Preamble
========

The licenses for most software are designed to take away your freedom
to share and change it.  By contrast, the GNU General Public License is
intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.


File: avram.info,  Node: Terms and Conditions,  Next: How to Apply,  Prev: Preamble,  Up: Copying

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
===============================================================

  1. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  3. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  6. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  7. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  8. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

 10. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 11. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY
 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

File: avram.info,  Node: How to Apply,  Prev: Terms and Conditions,  Up: Copying

How to Apply These Terms to Your New Programs
=============================================

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.  This is free software, and you are welcome
     to redistribute it under certain conditions; type `show c'
     for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: avram.info,  Node: Function Index,  Next: Concept Index,  Prev: Copying,  Up: Top

Function Index
**************

�[index�]
* Menu:

* *avm_matrix_of_list:                   Two dimensional arrays.
                                                              (line  61)
* *avm_matrix_reflection:                Related utility functions.
                                                              (line  41)
* *avm_matrix_transposition:             Related utility functions.
                                                              (line  14)
* *avm_packed_matrix_of_list:            Two dimensional arrays.
                                                              (line 194)
* *avm_row_number_array:                 Related utility functions.
                                                              (line  60)
* *avm_standard_unstrung:                Characters and Strings.
                                                              (line  92)
* *avm_unstrung:                         Characters and Strings.
                                                              (line  89)
* *avm_value_of_list:                    Primitive types.     (line  14)
* *avm_vector_of_list:                   One dimensional arrays.
                                                              (line  19)
* avm_anticipate:                        Indirection.         (line  36)
* avm_apply:                             The Universal Function.
                                                              (line  23)
* avm_area:                              Simple Operations.   (line 189)
* avm_binary_comparison:                 Comparison.          (line  63)
* avm_binary_membership:                 List Transformations.
                                                              (line  77)
* avm_byte_transduce:                    Execution Modes.     (line  71)
* avm_character_code:                    Characters and Strings.
                                                              (line  48)
* avm_character_representation:          Characters and Strings.
                                                              (line  35)
* avm_clearjmp:                          Suicidal exception handling.
                                                              (line  62)
* avm_comparison:                        Comparison.          (line  25)
* avm_concatenation:                     List Transformations.
                                                              (line  41)
* avm_copied:                            Simple Operations.   (line  40)
* avm_count_apply:                       The Universal Function.
                                                              (line  17)
* avm_count_branches:                    Indirection.         (line  29)
* avm_count_chrcodes:                    Characters and Strings.
                                                              (line 186)
* avm_count_cmdline:                     Command Line Parsing.
                                                              (line 176)
* avm_count_compare:                     Comparison.          (line  17)
* avm_count_decons:                      Deconstruction Functions.
                                                              (line  15)
* avm_count_exmodes:                     Execution Modes.     (line  90)
* avm_count_fnames:                      File Names.          (line  93)
* avm_count_formin:                      Formatted Input.     (line 132)
* avm_count_formout:                     Formatted Output.    (line 210)
* avm_count_instruct:                    Instruction Stacks.  (line 146)
* avm_count_libfuns:                     Calling existing library functions.
                                                              (line  60)
* avm_count_listfuns:                    List Transformations.
                                                              (line  21)
* avm_count_lists:                       Simple Operations.   (line  31)
* avm_count_matcon:                      Related utility functions.
                                                              (line  89)
* avm_count_mwrap:                       Memory leaks.        (line  62)
* avm_count_portals:                     Lists of Pairs of Ports.
                                                              (line  46)
* avm_count_ports:                       Ports and Packets.   (line  49)
* avm_count_profile:                     Profiling.           (line 105)
* avm_count_rawio:                       Raw Files.           (line  82)
* avm_date_representation:               File Names.          (line  43)
* avm_debug_memory:                      Memory leaks.        (line  31)
* avm_deconstruction:                    Deconstruction Functions.
                                                              (line  24)
* avm_default_command_line:              Command Line Parsing.
                                                              (line  14)
* avm_disable_interaction:               Execution Modes.     (line  54)
* avm_dispose:                           Simple Operations.   (line  23)
* avm_dispose_branch:                    Indirection.         (line 133)
* avm_dispose_branch_queue:              Indirection.         (line 122)
* avm_dispose_rows:                      Related utility functions.
                                                              (line  77)
* avm_distribution:                      List Transformations.
                                                              (line  35)
* avm_dont_debug_memory:                 Memory leaks.        (line  38)
* avm_dont_manage_memory:                Memory leaks.        (line  26)
* avm_enqueue:                           Simple Operations.   (line  98)
* avm_enqueue_branch:                    Indirection.         (line  68)
* avm_entries:                           Profiling.           (line  28)
* avm_environment:                       Command Line Parsing.
                                                              (line 126)
* avm_error:                             Error Reporting.     (line  37)
* avm_fatal_io_error:                    Error Reporting.     (line  44)
* avm_free_managed_memory:               Memory leaks.        (line  97)
* avm_have_library_call:                 Calling existing library functions.
                                                              (line  35)
* avm_initialize_apply:                  The Universal Function.
                                                              (line  11)
* avm_initialize_branches:               Indirection.         (line  23)
* avm_initialize_chrcodes:               Characters and Strings.
                                                              (line 180)
* avm_initialize_cmdline:                Command Line Parsing.
                                                              (line 171)
* avm_initialize_compare:                Comparison.          (line  12)
* avm_initialize_decons:                 Deconstruction Functions.
                                                              (line  10)
* avm_initialize_exmodes:                Execution Modes.     (line  85)
* avm_initialize_fnames:                 File Names.          (line  88)
* avm_initialize_formin:                 Formatted Input.     (line 126)
* avm_initialize_formout:                Formatted Output.    (line 205)
* avm_initialize_instruct:               Instruction Stacks.  (line 141)
* avm_initialize_libfuns:                Calling existing library functions.
                                                              (line  55)
* avm_initialize_listfuns:               List Transformations.
                                                              (line  16)
* avm_initialize_lists:                  Simple Operations.   (line  17)
* avm_initialize_matcon:                 Related utility functions.
                                                              (line  83)
* avm_initialize_mwrap:                  Memory leaks.        (line  54)
* avm_initialize_portals:                Lists of Pairs of Ports.
                                                              (line  40)
* avm_initialize_ports:                  Ports and Packets.   (line  45)
* avm_initialize_profile:                Profiling.           (line 100)
* avm_initialize_rawio:                  Raw Files.           (line  77)
* avm_interact:                          Execution Modes.     (line  12)
* avm_internal_error:                    Error Reporting.     (line  60)
* avm_join:                              Simple Operations.   (line  76)
* avm_length:                            Simple Operations.   (line 179)
* avm_library_call:                      Calling existing library functions.
                                                              (line  14)
* avm_line_map:                          Execution Modes.     (line  80)
* avm_list_of_matrix:                    Two dimensional arrays.
                                                              (line 135)
* avm_list_of_packed_matrix:             Two dimensional arrays.
                                                              (line 225)
* avm_list_of_value:                     Primitive types.     (line  47)
* avm_list_of_vector:                    One dimensional arrays.
                                                              (line  48)
* avm_load:                              Formatted Input.     (line  75)
* avm_manage_memory:                     Memory leaks.        (line  17)
* avm_measurement:                       List Transformations.
                                                              (line  82)
* avm_membership:                        List Transformations.
                                                              (line  60)
* avm_multiscanned:                      Characters and Strings.
                                                              (line 126)
* avm_natural:                           Simple Operations.   (line 194)
* avm_new_portal:                        Lists of Pairs of Ports.
                                                              (line  25)
* avm_newport:                           Ports and Packets.   (line  27)
* avm_non_fatal_io_error:                Error Reporting.     (line  55)
* avm_output:                            Formatted Output.    (line  11)
* avm_output_as_directed:                Formatted Output.    (line  80)
* avm_path_name:                         File Names.          (line  55)
* avm_path_representation:               File Names.          (line  12)
* avm_position:                          Simple Operations.   (line 212)
* avm_preamble_and_contents:             Formatted Input.     (line  12)
* avm_print_list:                        Simple Operations.   (line 202)
* avm_prior_to_version:                  Version Management.  (line  50)
* avm_program_name:                      Error Reporting.     (line  25)
* avm_prompt:                            Characters and Strings.
                                                              (line 143)
* avm_put_bytes:                         Formatted Output.    (line 191)
* avm_received_list:                     Raw Files.           (line  10)
* avm_reclamation_failure:               Error Reporting.     (line  73)
* avm_recoverable_anticipate:            Indirection.         (line  61)
* avm_recoverable_apply:                 The Universal Function.
                                                              (line  40)
* avm_recoverable_area:                  Recoverable Operations.
                                                              (line  38)
* avm_recoverable_enqueue:               Recoverable Operations.
                                                              (line  25)
* avm_recoverable_enqueue_branch:        Indirection.         (line 112)
* avm_recoverable_interact:              Execution Modes.     (line  60)
* avm_recoverable_join:                  Recoverable Operations.
                                                              (line  15)
* avm_recoverable_length:                Recoverable Operations.
                                                              (line  30)
* avm_recoverable_natural:               Recoverable Operations.
                                                              (line  47)
* avm_recoverable_prompt:                Characters and Strings.
                                                              (line 168)
* avm_recoverable_standard_strung:       Characters and Strings.
                                                              (line  83)
* avm_recoverable_strung:                Characters and Strings.
                                                              (line  80)
* avm_reschedule:                        Instruction Stacks.  (line 126)
* avm_retire:                            Instruction Stacks.  (line 104)
* avm_reversal:                          List Transformations.
                                                              (line  27)
* avm_scanned_list:                      Characters and Strings.
                                                              (line 107)
* avm_scheduled:                         Instruction Stacks.  (line  89)
* avm_seal:                              Lists of Pairs of Ports.
                                                              (line  32)
* avm_send_list:                         Raw Files.           (line  46)
* avm_set_program_name:                  Error Reporting.     (line  13)
* avm_set_version:                       Version Management.  (line  14)
* avm_setjmp:                            Suicidal exception handling.
                                                              (line  39)
* avm_setnonjump:                        Suicidal exception handling.
                                                              (line  90)
* avm_sever:                             Ports and Packets.   (line  36)
* avm_standard_character_code:           Characters and Strings.
                                                              (line  50)
* avm_standard_character_representation: Characters and Strings.
                                                              (line  37)
* avm_standard_strung:                   Characters and Strings.
                                                              (line  58)
* avm_strung:                            Characters and Strings.
                                                              (line  56)
* avm_tally:                             Profiling.           (line  67)
* avm_trace_interaction:                 Execution Modes.     (line  50)
* avm_transposition:                     List Transformations.
                                                              (line  49)
* avm_turn_off_stderr:                   Inept excess verbiage.
                                                              (line  34)
* avm_turn_off_stdout:                   Inept excess verbiage.
                                                              (line  18)
* avm_turn_on_stderr:                    Inept excess verbiage.
                                                              (line  40)
* avm_turn_on_stdout:                    Inept excess verbiage.
                                                              (line  26)
* avm_version:                           Version Management.  (line  81)
* avm_warning:                           Error Reporting.     (line  32)


File: avram.info,  Node: Concept Index,  Prev: Function Index,  Up: Top

Concept Index
*************

�[index�]
* Menu:

* absolute path:                         Input Data Structure.
                                                              (line  27)
* adaptive integration:                  gslint output.       (line  13)
* annotations <1>:                       Profiling.           (line  22)
* annotations:                           Note.                (line   9)
* API:                                   Library Reference.   (line  17)
* appending to files:                    Output From Non-interactive Applications.
                                                              (line  21)
* apply <1>:                             Exception Handler Usage.
                                                              (line  46)
* apply:                                 Variable Freedom.    (line  57)
* argz.h <1>:                            Command Line Parsing.
                                                              (line 121)
* argz.h:                                Configuration Related Errors.
                                                              (line  53)
* arrays:                                One dimensional arrays.
                                                              (line   7)
* ask-to-overwrite command line option:  Parameter Mode Options.
                                                              (line  18)
* asprintf <1>:                          math library exceptions.
                                                              (line  12)
* asprintf:                              math library conversion functions.
                                                              (line  12)
* assign:                                Assignment.          (line  22)
* assignment <1>:                        Error Messages.      (line  84)
* assignment:                            Assignment.          (line   6)
* asynchronous circuits:                 Transfer.            (line  91)
* author <1>:                            Operator Generalization.
                                                              (line  51)
* author <2>:                            Transfer.            (line  92)
* author:                                Internal Errors.     (line  23)
* autoconf:                              Implementing new library functions.
                                                              (line  49)
* automake:                              Implementing new library functions.
                                                              (line  49)
* avm_current_directory_prefix:          File Names.          (line  24)
* avm_packet:                            Ports and Packets.   (line   8)
* avm_parent_directory_prefix:           File Names.          (line  24)
* avm_path_separator:                    File Names.          (line  24)
* avm_path_separator_character:          File Names.          (line  24)
* avm_root_directory_prefix:             File Names.          (line  24)
* AVMINPUTS <1>:                         Environment.         (line   6)
* AVMINPUTS <2>:                         Configuration Related Errors.
                                                              (line  53)
* AVMINPUTS:                             i/o Errors.          (line  11)
* backward compatability <1>:            Calling existing library functions.
                                                              (line  22)
* backward compatability:                Characters and Strings.
                                                              (line  29)
* backward compatibility:                Configuration Related Errors.
                                                              (line  35)
* bad bessel function call:              Bessel function errors.
                                                              (line   7)
* bad character in file name <1>:        File Names.          (line  74)
* bad character in file name:            File Format Errors.  (line  32)
* bad derivative specification:          gsldif exceptions.   (line   6)
* bad integral specification:            gslint exceptions.   (line   8)
* bad kinsol specification:              kinsol exceptions.   (line  17)
* bad lapack specification:              lapack exceptions.   (line  13)
* bad matrix specification:              External Libraries.  (line  46)
* bad minpack specification:             minpack exceptions.  (line   9)
* bad mpfr specification:                mpfr exceptions.     (line   9)
* bad rmath specification:               rmath exceptions.    (line   8)
* bad umf specification:                 umf exceptions.      (line  13)
* bad vector specification:              External Libraries.  (line  46)
* bessel functions <1>:                  rmath miscellaneous functions.
                                                              (line  13)
* bessel functions:                      Bessel function calling conventions.
                                                              (line   6)
* bit strings:                           Concrete Syntax.     (line  15)
* booleans <1>:                          Input Data Structure.
                                                              (line  69)
* booleans:                              Representation of Numeric and Textual Data.
                                                              (line  33)
* bu <1>:                                Exception Handler Usage.
                                                              (line  46)
* bu <2>:                                Reduce.              (line  66)
* bu:                                    Refer.               (line  11)
* bug reports:                           Internal Errors.     (line  23)
* bugs:                                  Bugs.                (line   6)
* byte-transducer command line option <1>: Byte Transducers.  (line   6)
* byte-transducer command line option <2>: Loading All of Standard Input at Once.
                                                              (line   6)
* byte-transducer command line option:   Filter Mode Options. (line  40)
* C++ <1>:                               Implementing new library functions.
                                                              (line 118)
* C++:                                   Library Reference.   (line  57)
* c++filt utility:                       Implementing new library functions.
                                                              (line 119)
* can't close <1>:                       Profiling.           (line  84)
* can't close <2>:                       Formatted Output.    (line 176)
* can't close:                           i/o Errors.          (line  32)
* can't emulate version:                 Configuration Related Errors.
                                                              (line  35)
* can't read:                            i/o Errors.          (line  11)
* can't spawn:                           i/o Errors.          (line  27)
* can't write <1>:                       Profiling.           (line  84)
* can't write <2>:                       Formatted Output.    (line  66)
* can't write <3>:                       Raw Files.           (line  68)
* can't write:                           i/o Errors.          (line  20)
* cat <1>:                               Cat.                 (line   7)
* cat <2>:                               Transfer.            (line  71)
* cat:                                   Example Script.      (line  13)
* character codes <1>:                   Byte Transducers.    (line  45)
* character codes <2>:                   Representation of Numeric and Textual Data.
                                                              (line  25)
* character codes:                       Blocking.            (line  26)
* character encodings:                   Characters and Strings.
                                                              (line  14)
* character representations:             Character Table.     (line   6)
* character strings <1>:                 Characters and Strings.
                                                              (line   6)
* character strings <2>:                 Error Messages.      (line  13)
* character strings <3>:                 Standard Output Representation.
                                                              (line  38)
* character strings:                     Representation of Numeric and Textual Data.
                                                              (line  19)
* checksums:                             File Format.         (line  21)
* chmod:                                 Example Script.      (line  24)
* choice-of-output command line option <1>: Standard Output Representation.
                                                              (line   6)
* choice-of-output command line option <2>: Standard Input Representation.
                                                              (line  12)
* choice-of-output command line option:  Filter Mode Options. (line  21)
* Cholesky decomposition <1>:            Additional lapack notes.
                                                              (line  28)
* Cholesky decomposition:                lapack calling conventions.
                                                              (line  73)
* coding standards:                      Implementing new library functions.
                                                              (line 153)
* column major order <1>:                umf input parameters.
                                                              (line  49)
* column major order <2>:                Related utility functions.
                                                              (line  25)
* column major order:                    Two dimensional arrays.
                                                              (line 140)
* combinators:                           Recursion.           (line   7)
* command line <1>:                      Command Line Parsing.
                                                              (line   6)
* command line <2>:                      Character Oriented Interaction.
                                                              (line   8)
* command line <3>:                      Line Oriented Interaction.
                                                              (line   8)
* command line <4>:                      Input for Mapped Applications.
                                                              (line  26)
* command line <5>:                      Input Data Structure.
                                                              (line   7)
* command line:                          Command Line Syntax. (line   6)
* compare <1>:                           Comparison.          (line  12)
* compare:                               Compare.             (line   6)
* compare combinator <1>:                mpfr binary predicates.
                                                              (line  27)
* compare combinator:                    Additional math library notes.
                                                              (line  16)
* complex numbers:                       complex.             (line   6)
* compose <1>:                           How avram Thinks.    (line 112)
* compose:                               Standard Library.    (line  10)
* compression:                           Weight.              (line  20)
* concatenation <1>:                     List Transformations.
                                                              (line  41)
* concatenation <2>:                     Cat.                 (line   7)
* concatenation:                         Transfer.            (line  71)
* concurrency:                           Instruction Stacks.  (line  23)
* conditional <1>:                       How avram Thinks.    (line 112)
* conditional:                           Standard Library.    (line  10)
* conjugate transpose:                   umf.                 (line  26)
* cons <1>:                              Operator Generalization.
                                                              (line   6)
* cons <2>:                              A New Operator.      (line  13)
* cons:                                  Raw Material.        (line  54)
* constant <1>:                          How avram Thinks.    (line 112)
* constant:                              Standard Library.    (line  10)
* constrained non-linear optimization:   kinsol.              (line   8)
* constrained optimization:              Additional minpack notes.
                                                              (line  17)
* constraints <1>:                       Additional kinsol notes.
                                                              (line  20)
* constraints:                           Additional glpk notes.
                                                              (line   9)
* convergence:                           gslevu.              (line  15)
* copyright:                             Implementing new library functions.
                                                              (line 151)
* correlation:                           Additional lapack notes.
                                                              (line  31)
* counter <1>:                           Ports and Packets.   (line   8)
* counter:                               Simple Operations.   (line 179)
* counter overflow <1>:                  File Names.          (line  74)
* counter overflow:                      Overflow Errors.     (line   7)
* couple:                                Standard Library.    (line  10)
* covariance matrix <1>:                 Additional lapack notes.
                                                              (line  32)
* covariance matrix:                     Interaction combinator.
                                                              (line  21)
* cumulative probability:                rmath statistical functions.
                                                              (line  86)
* current time:                          Input Data Structure.
                                                              (line  21)
* date:                                  Input Data Structure.
                                                              (line  21)
* deadlock <1>:                          Execution Modes.     (line  46)
* deadlock <2>:                          Interaction combinator.
                                                              (line  95)
* deadlock:                              Line Oriented Interaction.
                                                              (line  98)
* Debian <1>:                            Additional minpack notes.
                                                              (line  31)
* Debian:                                Implementing new library functions.
                                                              (line 124)
* debugging:                             Exception Handler Usage.
                                                              (line  64)
* deconstruction <1>:                    Deconstruction Functions.
                                                              (line   6)
* deconstruction <2>:                    Exception Handler Usage.
                                                              (line  17)
* deconstruction <3>:                    Deconstruction.      (line   6)
* deconstruction:                        Bit String Encoding. (line  37)
* default file extensions:               Parameter Mode Options.
                                                              (line  26)
* default-to-stdin command line option <1>: Example Script.   (line  13)
* default-to-stdin command line option:  Parameter Mode Options.
                                                              (line  37)
* denotational semantics:                Semantics.           (line  31)
* diagnostics:                           Diagnostics.         (line   6)
* dimensionality reduction:              Additional lapack notes.
                                                              (line   7)
* discontiguous field:                   Comparison.          (line  43)
* distribute:                            Distribute.          (line   7)
* distributed implementation <1>:        Reduce.              (line  57)
* distributed implementation:            Bit String Encoding. (line  15)
* distributions:                         rmath statistical functions.
                                                              (line  13)
* eigenvectors:                          lapack calling conventions.
                                                              (line  64)
* email:                                 Internal Errors.     (line  23)
* emulation:                             General Options.     (line   9)
* emulation command line option <1>:     Configuration Related Errors.
                                                              (line  35)
* emulation command line option:         General Options.     (line   9)
* environment <1>:                       Command Line Parsing.
                                                              (line 126)
* environment <2>:                       Input Data Structure.
                                                              (line   7)
* environment <3>:                       Environment.         (line   6)
* environment <4>:                       Configuration Related Errors.
                                                              (line  53)
* environment <5>:                       i/o Errors.          (line  11)
* environment:                           Preface.             (line  11)
* eof:                                   Interaction combinator.
                                                              (line  87)
* equality <1>:                          Compare.             (line  22)
* equality <2>:                          Variable Freedom.    (line  56)
* equality:                              On Equality.         (line   6)
* error messages <1>:                    Error Reporting.     (line   6)
* error messages <2>:                    List Transformations.
                                                              (line   8)
* error messages <3>:                    Expedient Error Messages.
                                                              (line   6)
* error messages:                        Diagnostics.         (line   6)
* exceptions <1>:                        List Transformations.
                                                              (line   8)
* exceptions <2>:                        Computable Error Messages.
                                                              (line  14)
* exceptions <3>:                        Exception Handling.  (line   6)
* exceptions <4>:                        A Minimal Set of Properties.
                                                              (line  58)
* exceptions:                            Bugs.                (line   6)
* executable files <1>:                  Formatted Output.    (line  59)
* executable files:                      Example Script.      (line  23)
* exp_popen <1>:                         Line Oriented Interaction.
                                                              (line  32)
* exp_popen:                             i/o Errors.          (line  27)
* expect:                                i/o Errors.          (line  27)
* EXT command line option <1>:           Environment.         (line  25)
* EXT command line option:               Parameter Mode Options.
                                                              (line  26)
* extensions <1>:                        Other Diagnostics and Warnings.
                                                              (line   7)
* extensions:                            Parameter Mode Options.
                                                              (line  26)
* external-libraries:                    General Options.     (line  28)
* facilitator:                           Ports and Packets.   (line 124)
* fan:                                   Fan.                 (line   6)
* feclearexcept:                         Additional math library notes.
                                                              (line  10)
* field <1>:                             Error Messages.      (line  80)
* field <2>:                             Assignment.          (line  77)
* field:                                 Field.               (line  29)
* file extensions:                       Other Diagnostics and Warnings.
                                                              (line   7)
* file format <1>:                       Standard Input Representation.
                                                              (line  40)
* file format:                           File Format.         (line   6)
* file name extensions <1>:              Other Diagnostics and Warnings.
                                                              (line   7)
* file name extensions:                  Parameter Mode Options.
                                                              (line  26)
* file name suffixes <1>:                Other Diagnostics and Warnings.
                                                              (line   7)
* file name suffixes:                    Parameter Mode Options.
                                                              (line  26)
* file names <1>:                        File Names.          (line   6)
* file names <2>:                        Input Data Structure.
                                                              (line  27)
* file names:                            i/o Errors.          (line  11)
* file parameters:                       Command Line Syntax. (line  13)
* filter:                                Filter.              (line   6)
* filter mode <1>:                       Filter Mode Interface.
                                                              (line   6)
* filter mode <2>:                       Security.            (line  11)
* filter mode:                           Filter Mode.         (line   6)
* flag:                                  Ports and Packets.   (line   8)
* flat:                                  Transpose.           (line  17)
* fold:                                  Reduce.              (line  43)
* force-text-input command line option <1>: Standard Input Representation.
                                                              (line  12)
* force-text-input command line option:  General Options.     (line  47)
* Fortran <1>:                           lapack.              (line   6)
* Fortran <2>:                           Implementing new library functions.
                                                              (line 112)
* Fortran <3>:                           External Library Maintenance.
                                                              (line  10)
* Fortran:                               Two dimensional arrays.
                                                              (line 124)
* Fourier transforms <1>:                harminv.             (line   9)
* Fourier transforms:                    fftw.                (line   6)
* ftp:                                   Interaction combinator.
                                                              (line  47)
* functional programming <1>:            Exception Handler Usage.
                                                              (line  64)
* functional programming <2>:            List Combinators.    (line   6)
* functional programming <3>:            Recursion.           (line   7)
* functional programming <4>:            User Manual.         (line  26)
* functional programming:                Preface.             (line  11)
* gamma functions <1>:                   rmath miscellaneous functions.
                                                              (line   7)
* gamma functions:                       mpfr unary operators.
                                                              (line   7)
* generalized least squares <1>:         Additional lapack notes.
                                                              (line  22)
* generalized least squares:             lapack calling conventions.
                                                              (line  89)
* gmp library:                           Additional mpfr notes.
                                                              (line   7)
* GNU R:                                 Interaction combinator.
                                                              (line  18)
* GNU Scientific Library:                gsldif output.       (line  10)
* grammar:                               Syntax.              (line   8)
* guard <1>:                             Exception Handler Usage.
                                                              (line  46)
* guard:                                 Computable Error Messages.
                                                              (line  41)
* harminv:                               harminv.             (line   6)
* Hartley transforms:                    fftw.                (line   6)
* head field:                            Lists.               (line   7)
* header file <1>:                       Additional minpack notes.
                                                              (line  27)
* header file:                           Implementing new library functions.
                                                              (line  12)
* help:                                  General Options.     (line   9)
* help command line option <1>:          Other Diagnostics and Warnings.
                                                              (line  20)
* help command line option:              General Options.     (line   9)
* Hermitian matrix:                      lapack calling conventions.
                                                              (line 121)
* hired <1>:                             Exception Handler Usage.
                                                              (line  46)
* hired:                                 Variable Freedom.    (line   8)
* home page:                             General Options.     (line  22)
* I need avram linked with:              Configuration Related Errors.
                                                              (line  24)
* i/o errors:                            i/o Errors.          (line   6)
* identifiers:                           How avram Thinks.    (line  15)
* identity <1>:                          Exception Handler Usage.
                                                              (line  46)
* identity:                              Standard Library.    (line  10)
* identity function:                     Concrete Syntax.     (line   7)
* imperative programming <1>:            Exception Handler Usage.
                                                              (line  64)
* imperative programming <2>:            List Combinators.    (line   6)
* imperative programming:                Assignment.          (line   6)
* impetus:                               Ports and Packets.   (line 115)
* improper integrals:                    Additional gslint notes.
                                                              (line   8)
* include directives:                    Implementing new library functions.
                                                              (line  54)
* infinite series:                       gslevu.              (line  14)
* infinite streams <1>:                  Byte Transducers.    (line   7)
* infinite streams <2>:                  Line Maps.           (line  17)
* infinite streams:                      Loading All of Standard Input at Once.
                                                              (line   9)
* infinite sum:                          gslevu calling conventions.
                                                              (line  13)
* input files:                           Command Line Syntax. (line  13)
* insert <1>:                            Insert.              (line   6)
* insert:                                Sort.                (line  29)
* instruction_node:                      Instruction Stacks.  (line   7)
* interactive applications <1>:          Characters and Strings.
                                                              (line 161)
* interactive applications <2>:          Security.            (line  32)
* interactive applications:              Parameter Mode Options.
                                                              (line  59)
* interactive command line option <1>:   Output From Interactive Applications.
                                                              (line   6)
* interactive command line option <2>:   Output From Non-interactive Applications.
                                                              (line   6)
* interactive command line option:       Parameter Mode Options.
                                                              (line  59)
* internal error:                        Memory leaks.        (line  86)
* internal errors <1>:                   Bugs.                (line   6)
* internal errors:                       Internal Errors.     (line   6)
* interpretation:                        Ports and Packets.   (line 115)
* invalid asprintf specifier:            math library exceptions.
                                                              (line  11)
* invalid assignment:                    Application Programming Errors.
                                                              (line  27)
* invalid comparison:                    Application Programming Errors.
                                                              (line  15)
* invalid concatenation:                 Application Programming Errors.
                                                              (line  25)
* invalid deconstruction:                Application Programming Errors.
                                                              (line  17)
* invalid distribution:                  Application Programming Errors.
                                                              (line  23)
* invalid file name:                     File Names.          (line  74)
* invalid file specification <1>:        Formatted Output.    (line 176)
* invalid file specification:            File Format Errors.  (line  43)
* invalid membership:                    Application Programming Errors.
                                                              (line  21)
* invalid output preamble format <1>:    Formatted Output.    (line  66)
* invalid output preamble format:        File Format Errors.  (line  36)
* invalid profile identifier <1>:        Profiling.           (line  84)
* invalid profile identifier:            Application Programming Errors.
                                                              (line  31)
* invalid raw file format <1>:           Formatted Input.     (line 113)
* invalid raw file format <2>:           Raw Files.           (line  31)
* invalid raw file format:               File Format Errors.  (line  48)
* invalid recursion:                     Application Programming Errors.
                                                              (line  13)
* invalid text format <1>:               math library exceptions.
                                                              (line  17)
* invalid text format <2>:               Formatted Output.    (line  66)
* invalid text format:                   File Format Errors.  (line  12)
* invalid transpose:                     Application Programming Errors.
                                                              (line  19)
* invalid value <1>:                     math library exceptions.
                                                              (line   8)
* invalid value <2>:                     External Libraries.  (line  46)
* invalid value:                         Primitive types.     (line  41)
* isolate <1>:                           Assignment.          (line  48)
* isolate:                               Variable Freedom.    (line  38)
* iterate <1>:                           Reduce.              (line  66)
* iterate:                               Iteration.           (line   6)
* Jacobian <1>:                          Additional minpack notes.
                                                              (line  12)
* Jacobian <2>:                          minpack calling conventions.
                                                              (line  15)
* Jacobian <3>:                          Additional kinsol notes.
                                                              (line   6)
* Jacobian:                              kinsol input parameters.
                                                              (line  17)
* jail:                                  General Options.     (line  36)
* Java:                                  Preface.             (line 126)
* lapack error:                          lapack exceptions.   (line  18)
* least squares <1>:                     minpack.             (line   7)
* least squares <2>:                     Additional lapack notes.
                                                              (line  15)
* least squares <3>:                     lapack calling conventions.
                                                              (line  89)
* least squares:                         harminv.             (line   9)
* left <1>:                              Error Messages.      (line  82)
* left <2>:                              Field.               (line   6)
* left:                                  Standard Library.    (line  10)
* Levin u-transform:                     gslevu.              (line  16)
* libexpect:                             i/o Errors.          (line  27)
* library interfac source file:          Implementing new library functions.
                                                              (line  35)
* library interface header file:         Implementing new library functions.
                                                              (line  12)
* library modules:                       Standard Library.    (line   7)
* licensing restrictions:                Implementing new library functions.
                                                              (line 143)
* line breaks <1>:                       Formatted Output.    (line  45)
* line breaks <2>:                       Formatted Input.     (line  56)
* line breaks:                           Character Oriented Interaction.
                                                              (line  30)
* line-map command line option <1>:      Line Maps.           (line   6)
* line-map command line option <2>:      Loading All of Standard Input at Once.
                                                              (line   6)
* line-map command line option:          Filter Mode Options. (line  29)
* linear algebra:                        lapack.              (line   7)
* linear programming <1>:                lpsolve calling conventions.
                                                              (line   7)
* linear programming <2>:                lpsolve.             (line   6)
* linear programming:                    glpk.                (line   7)
* lists <1>:                             Lists.               (line   7)
* lists <2>:                             List Functions.      (line   6)
* lists <3>:                             List Combinators.    (line   6)
* lists <4>:                             A Minimal Set of Properties.
                                                              (line  58)
* lists <5>:                             Representation of Numeric and Textual Data.
                                                              (line  19)
* lists:                                 Raw Material.        (line  12)
* LU decomposition:                      Two dimensional arrays.
                                                              (line  56)
* map:                                   Map.                 (line  12)
* map-to-each-file command line option <1>: Input for Mapped Applications.
                                                              (line   6)
* map-to-each-file command line option:  Parameter Mode Options.
                                                              (line  46)
* mapcur:                                Mapcur.              (line   6)
* matrices:                              Two dimensional arrays.
                                                              (line   8)
* matrix memory map:                     Two dimensional arrays.
                                                              (line 172)
* member <1>:                            List Transformations.
                                                              (line  60)
* member:                                Member.              (line   6)
* memory overflow <1>:                   File Names.          (line  74)
* memory overflow:                       Overflow Errors.     (line   7)
* meta <1>:                              Recur.               (line   6)
* meta:                                  Standard Library.    (line  10)
* minpack error:                         minpack exceptions.  (line  12)
* missing value <1>:                     math library exceptions.
                                                              (line   8)
* missing value <2>:                     External Libraries.  (line  46)
* missing value:                         Primitive types.     (line  40)
* mixed integer programming <1>:         lpsolve calling conventions.
                                                              (line  12)
* mixed integer programming:             lpsolve.             (line   6)
* mnemonics:                             Standard Library.    (line  30)
* modes <1>:                             Filter Mode Interface.
                                                              (line   6)
* modes <2>:                             Filter Mode.         (line   6)
* modes:                                 Modes of Operation.  (line   8)
* mpfr error:                            mpfr exceptions.     (line  12)
* multiple -.EXT options:                Other Diagnostics and Warnings.
                                                              (line   7)
* multiple character encodings:          Characters and Strings.
                                                              (line  14)
* multiple version specifications:       Configuration Related Errors.
                                                              (line  41)
* multivariate normal distrubution:      Interaction combinator.
                                                              (line  20)
* nan <1>:                               mpfr constants.      (line  26)
* nan:                                   Additional math library notes.
                                                              (line   7)
* native integer arithmetic <1>:         List Transformations.
                                                              (line  87)
* native integer arithmetic:             Weight.              (line  30)
* naturals <1>:                          Simple Operations.   (line 194)
* naturals <2>:                          Input Data Structure.
                                                              (line  60)
* naturals:                              Representation of Numeric and Textual Data.
                                                              (line  50)
* nil <1>:                               Standard Library.    (line  10)
* nil <2>:                               Representation of Numeric and Textual Data.
                                                              (line   9)
* nil:                                   Raw Material.        (line  50)
* nm utility:                            Implementing new library functions.
                                                              (line 118)
* non-adaptive integration:              gslint output.       (line  13)
* non-convergence:                       kinsol output.       (line  14)
* non-linear optimization <1>:           minpack.             (line   6)
* non-linear optimization:               kinsol.              (line   7)
* non-local jumps:                       Suicidal exception handling.
                                                              (line  15)
* non-standard installation:             Example Script.      (line  26)
* not writing file name:                 Formatted Output.    (line 150)
* note <1>:                              Profile.             (line  22)
* note:                                  Note.                (line   9)
* null character in file name <1>:       File Names.          (line  74)
* null character in file name:           File Format Errors.  (line  29)
* numerical differentiation:             gsldif.              (line   6)
* numerical integration:                 gslint.              (line   6)
* operator precedence:                   Syntax.              (line  20)
* operator properties:                   A Minimal Set of Properties.
                                                              (line  36)
* optimization:                          kinsol.              (line   7)
* overflow <1>:                          List Transformations.
                                                              (line   8)
* overflow <2>:                          Simple Operations.   (line   9)
* overflow <3>:                          Weight.              (line  30)
* overflow:                              Overflow Errors.     (line   7)
* packed arrays:                         Two dimensional arrays.
                                                              (line 158)
* pairs:                                 Representation of Numeric and Textual Data.
                                                              (line  37)
* pairwise <1>:                          Pairwise.            (line   6)
* pairwise:                              Reduce.              (line  66)
* parameter mode <1>:                    Parameter Mode Interface.
                                                              (line   6)
* parameter mode <2>:                    Filter Mode Interface.
                                                              (line   6)
* parameter mode <3>:                    Security.            (line  20)
* parameter mode <4>:                    Parameter Mode Options.
                                                              (line   6)
* parameter mode:                        Parameter Mode.      (line   6)
* parameterized command line option:     Parameter Mode Options.
                                                              (line  90)
* path separators:                       Command Line Syntax. (line  43)
* paths <1>:                             Output From Non-interactive Applications.
                                                              (line  16)
* paths <2>:                             Input Data Structure.
                                                              (line  27)
* paths <3>:                             Environment.         (line   6)
* paths <4>:                             Example Script.      (line  24)
* paths:                                 Configuration Related Errors.
                                                              (line  53)
* pointer equality <1>:                  Comparison.          (line  31)
* pointer equality:                      On Equality.         (line  39)
* pointers <1>:                          Indirection.         (line   6)
* pointers <2>:                          Comparison.          (line  40)
* pointers <3>:                          Vacant Address Space.
                                                              (line  55)
* pointers <4>:                          On Equality.         (line  39)
* pointers:                              Preface.             (line 126)
* port:                                  Lists of Pairs of Ports.
                                                              (line   6)
* port_pair:                             Lists of Pairs of Ports.
                                                              (line  11)
* portability <1>:                       Suicidal exception handling.
                                                              (line 129)
* portability:                           Inept excess verbiage.
                                                              (line  60)
* portal:                                Lists of Pairs of Ports.
                                                              (line  11)
* preamble <1>:                          Formatted Output.    (line   7)
* preamble <2>:                          Formatted Input.     (line  27)
* preamble <3>:                          Raw Files.           (line  62)
* preamble <4>:                          Output From Non-interactive Applications.
                                                              (line  16)
* preamble <5>:                          Input Data Structure.
                                                              (line  39)
* preamble <6>:                          Standard Output Representation.
                                                              (line  22)
* preamble <7>:                          Standard Input Representation.
                                                              (line  47)
* preamble:                              Preamble Section.    (line   6)
* precedence:                            Syntax.              (line  20)
* precision <1>:                         mpfr binary operators with a natural operand.
                                                              (line  27)
* precision:                             mpfr binary operators.
                                                              (line  44)
* predicates <1>:                        math library predicates.
                                                              (line   6)
* predicates:                            Predicates.          (line   6)
* printing algorithm <1>:                Standard Output Representation.
                                                              (line  38)
* printing algorithm:                    Bit String Encoding. (line  21)
* probability distributions:             rmath statistical functions.
                                                              (line  13)
* profile.h:                             Profiling.           (line   6)
* profile.txt <1>:                       Profile.             (line   6)
* profile.txt:                           Files.               (line   7)
* prompts:                               Line Oriented Interaction.
                                                              (line  51)
* properties:                            A Minimal Set of Properties.
                                                              (line  36)
* queues <1>:                            Indirection.         (line  15)
* queues <2>:                            Simple Operations.   (line  98)
* queues:                                Bit String Encoding. (line  20)
* quiet command line option:             Parameter Mode Options.
                                                              (line  12)
* random number generators:              Implementing new library functions.
                                                              (line 169)
* random numbers <1>:                    mpfr functions with miscellaneous calling conventions.
                                                              (line  17)
* random numbers:                        mtwist.              (line   6)
* raw-mode command line option:          Standard Input Representation.
                                                              (line   8)
* raw-output command line option <1>:    Standard Output Representation.
                                                              (line   6)
* raw-output command line option:        Filter Mode Options. (line  12)
* re-entrancy:                           Additional minpack notes.
                                                              (line  20)
* recur <1>:                             Error Messages.      (line  77)
* recur:                                 Recur.               (line   6)
* recursion <1>:                         Comparison.          (line  58)
* recursion <2>:                         Mapcur.              (line  11)
* recursion <3>:                         Reduce.              (line  62)
* recursion <4>:                         Iteration.           (line   6)
* recursion:                             Recursion.           (line   6)
* reduce:                                Reduce.              (line   6)
* reductions:                            Profiling.           (line  79)
* refer:                                 Refer.               (line   6)
* reference count <1>:                   Simple Operations.   (line  71)
* reference count:                       Vacant Address Space.
                                                              (line  58)
* relative path:                         Input Data Structure.
                                                              (line  27)
* replace <1>:                           Replace.             (line   6)
* replace <2>:                           Error Messages.      (line  84)
* replace:                               Assignment.          (line  42)
* reverse:                               Reverse.             (line   6)
* right <1>:                             Error Messages.      (line  82)
* right <2>:                             Reduce.              (line  66)
* right <3>:                             Field.               (line   6)
* right:                                 Standard Library.    (line  10)
* rounding:                              mpfr.                (line  32)
* row major order:                       Related utility functions.
                                                              (line  49)
* run time errors:                       Diagnostics.         (line   6)
* score:                                 Profiling.           (line  14)
* script:                                Example Script.      (line   6)
* search paths <1>:                      Environment.         (line  11)
* search paths:                          Configuration Related Errors.
                                                              (line  53)
* search paths not supported <1>:        Command Line Parsing.
                                                              (line 117)
* search paths not supported:            Configuration Related Errors.
                                                              (line  53)
* security <1>:                          Command Line Parsing.
                                                              (line 167)
* security <2>:                          Formatted Output.    (line 167)
* security:                              Security.            (line   6)
* segmentation fault <1>:                math library exceptions.
                                                              (line  14)
* segmentation fault <2>:                gslint input parameters.
                                                              (line  27)
* segmentation fault <3>:                Additional gsldif notes.
                                                              (line  10)
* segmentation fault <4>:                Related utility functions.
                                                              (line  37)
* segmentation fault <5>:                Two dimensional arrays.
                                                              (line 239)
* segmentation fault <6>:                One dimensional arrays.
                                                              (line  59)
* segmentation fault <7>:                Primitive types.     (line  63)
* segmentation fault:                    Simple Operations.   (line  57)
* semantic function <1>:                 Error Messages.      (line  14)
* semantic function:                     Semantics.           (line  11)
* setjmp <1>:                            Additional gslint notes.
                                                              (line  14)
* setjmp:                                Suicidal exception handling.
                                                              (line  23)
* shell <1>:                             Output From Interactive Applications.
                                                              (line   9)
* shell <2>:                             i/o Errors.          (line  27)
* shell:                                 Command Line Syntax. (line  13)
* shell script <1>:                      Environment.         (line  17)
* shell script:                          Example Script.      (line   6)
* silly:                                 A Simple Lisp Like Language.
                                                              (line   6)
* silly-me:                              Error Messages.      (line  13)
* single precision:                      lapack.              (line  17)
* singular value decomposition:          lapack calling conventions.
                                                              (line  51)
* slow convergence:                      gslint exceptions.   (line  15)
* sort:                                  Sort.                (line   6)
* sparse matrices:                       umf.                 (line   6)
* sparse matrix <1>:                     Additional glpk notes.
                                                              (line   6)
* sparse matrix:                         glpk input parameters.
                                                              (line  18)
* spawning processes <1>:                Library Reference.   (line  39)
* spawning processes <2>:                Character Oriented Interaction.
                                                              (line  13)
* spawning processes <3>:                Line Oriented Interaction.
                                                              (line  26)
* spawning processes:                    i/o Errors.          (line  27)
* standard character encoding:           Characters and Strings.
                                                              (line  23)
* standard input <1>:                    File Names.          (line  63)
* standard input <2>:                    Output From Non-interactive Applications.
                                                              (line  16)
* standard input <3>:                    Line Maps.           (line  13)
* standard input <4>:                    Standard Input Representation.
                                                              (line   6)
* standard input <5>:                    Loading All of Standard Input at Once.
                                                              (line   6)
* standard input <6>:                    Filter Mode Interface.
                                                              (line  11)
* standard input <7>:                    Security.            (line  20)
* standard input <8>:                    Parameter Mode Options.
                                                              (line  37)
* standard input <9>:                    Filter Mode.         (line  27)
* standard input:                        User Manual.         (line  17)
* standard library:                      Refer.               (line  44)
* standard output <1>:                   Formatted Output.    (line 165)
* standard output <2>:                   File Names.          (line  63)
* standard output <3>:                   Simple Operations.   (line 204)
* standard output <4>:                   Output From Non-interactive Applications.
                                                              (line  16)
* standard output <5>:                   Line Maps.           (line  14)
* standard output:                       Standard Output Representation.
                                                              (line   6)
* standard prelude:                      Standard Library.    (line   7)
* state dependence:                      Implementing new library functions.
                                                              (line 139)
* state transition function:             Transfer.            (line  12)
* statistical distributions:             rmath statistical functions.
                                                              (line  13)
* step command line option <1>:          Output From Interactive Applications.
                                                              (line   6)
* step command line option <2>:          Output From Non-interactive Applications.
                                                              (line   6)
* step command line option:              Parameter Mode Options.
                                                              (line  67)
* storage locations:                     Assignment.          (line  37)
* strerror <1>:                          Profiling.           (line  96)
* strerror <2>:                          Error Reporting.     (line  48)
* strerror <3>:                          Formatted Output.    (line  74)
* strerror <4>:                          Raw Files.           (line  72)
* strerror:                              i/o Errors.          (line   7)
* strings <1>:                           Error Messages.      (line  13)
* strings:                               Representation of Numeric and Textual Data.
                                                              (line  19)
* strtod:                                math library conversion functions.
                                                              (line   6)
* symmetric matrices:                    lapack calling conventions.
                                                              (line  17)
* symmetric matrix:                      Two dimensional arrays.
                                                              (line  54)
* syntax:                                Syntax.              (line   8)
* system time:                           Input Data Structure.
                                                              (line  21)
* tail field:                            Lists.               (line   7)
* text files <1>:                        Input Data Structure.
                                                              (line  47)
* text files <2>:                        Standard Input Representation.
                                                              (line  47)
* text files:                            File Format.         (line  17)
* threads <1>:                           Instruction Stacks.  (line  77)
* threads:                               Library Reference.   (line  33)
* time stamp:                            Input Data Structure.
                                                              (line  21)
* tolerance <1>:                         minpack calling conventions.
                                                              (line  22)
* tolerance <2>:                         kinsol output.       (line  18)
* tolerance:                             gslint input parameters.
                                                              (line  11)
* trace command line option:             Parameter Mode Options.
                                                              (line  79)
* transfer:                              Transfer.            (line   6)
* transition <1>:                        Transition.          (line  11)
* transition:                            Transfer.            (line  24)
* transpose <1>:                         List Transformations.
                                                              (line  52)
* transpose <2>:                         Error Messages.      (line  77)
* transpose:                             Transpose.           (line  12)
* trees <1>:                             Indirection.         (line  70)
* trees <2>:                             Vacant Address Space.
                                                              (line  72)
* trees <3>:                             A Hierarchy of Sets. (line  27)
* trees <4>:                             Representation of Numeric and Textual Data.
                                                              (line   9)
* trees <5>:                             Bit String Encoding. (line   6)
* trees:                                 Raw Material.        (line 109)
* triangular matrices:                   lapack calling conventions.
                                                              (line  19)
* triangular matrix:                     Two dimensional arrays.
                                                              (line  34)
* trigonometric functions:               math library operators.
                                                              (line   6)
* Turing equivalence:                    A Minimal Set of Properties.
                                                              (line  58)
* type tags:                             Note.                (line  26)
* types:                                 Representation of Numeric and Textual Data.
                                                              (line  60)
* ulimit:                                Overflow Errors.     (line  28)
* umf error:                             umf exceptions.      (line  17)
* undefined expressions <1>:             Operator Generalization.
                                                              (line  50)
* undefined expressions:                 On Equality.         (line  32)
* universal function:                    The Universal Function.
                                                              (line   6)
* universal quantification <1>:          Operator Generalization.
                                                              (line  42)
* universal quantification <2>:          A Hierarchy of Sets. (line  29)
* universal quantification:              On Equality.         (line  32)
* universality <1>:                      Vacant Address Space.
                                                              (line  45)
* universality:                          A Minimal Set of Properties.
                                                              (line  58)
* Unix <1>:                              Character Oriented Interaction.
                                                              (line  32)
* Unix <2>:                              Input Data Structure.
                                                              (line  21)
* Unix <3>:                              Byte Transducers.    (line  42)
* Unix <4>:                              Example Script.      (line  13)
* Unix <5>:                              Command Line Syntax. (line  78)
* Unix:                                  Preface.             (line  11)
* unknown date:                          File Names.          (line  52)
* unparameterized command line option <1>: Standard Input Representation.
                                                              (line   8)
* unparameterized command line option:   Filter Mode Options. (line  50)
* unrecognized combinator <1>:           Vacant Address Space.
                                                              (line  26)
* unrecognized combinator:               Application Programming Errors.
                                                              (line  29)
* unrecognized function name:            External Libraries.  (line  32)
* unrecognized library:                  External Libraries.  (line  32)
* unrecognized option:                   Configuration Related Errors.
                                                              (line  47)
* unsupported hook <1>:                  Vacant Address Space.
                                                              (line  26)
* unsupported hook <2>:                  Configuration Related Errors.
                                                              (line  15)
* unsupported hook:                      Application Programming Errors.
                                                              (line  33)
* url:                                   General Options.     (line  22)
* value field:                           Type Conversions.    (line  29)
* variables:                             Variable Freedom.    (line  38)
* vectors:                               One dimensional arrays.
                                                              (line   8)
* verbosity setting:                     Inept excess verbiage.
                                                              (line  12)
* version:                               Version.             (line   8)
* versions <1>:                          Version Management.  (line   6)
* versions:                              Configuration Related Errors.
                                                              (line  35)
* web page:                              General Options.     (line  22)
* weight:                                Weight.              (line   7)
* wild cards:                            Have combinator.     (line  62)
* wish:                                  Example Script.      (line  28)
* writing file name:                     Formatted Output.    (line 150)