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' 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 ... 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 ... { 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 ... 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)