This is algae.info, produced by makeinfo version 4.3 from algae.texinfo.

INFO-DIR-SECTION Programming Languages
START-INFO-DIR-ENTRY
* algae: (algae).		Another Matrix Programming Language
END-INFO-DIR-ENTRY


File: algae.info,  Node: cd,  Next: eval,  Prev: builtin,  Up: Execution

 - Function: cd ( path )
     The `cd' function changes the current default directory to that
     specified by the character scalar PATH.  If PATH is NULL, the
     directory is changed to that given by the `HOME' environment
     variable.

     An exception is raised if an error occurs; otherwise, `cd' returns
     the integer 1.


File: algae.info,  Node: eval,  Next: exception,  Prev: cd,  Up: Execution

 - Function: eval ( s )
     The `eval' function evaluates the string S as an expression and
     returns its value.  Variable references, if any, have global scope.
     For example, consider the following interaction:

          > x = 0.5;
          > str = "sin(x)";
          > eval (str)
                  0.4794
          > x = 1.0;
          > eval (str)
                  0.8415

     Although the value of `str' remains `"sin(x)"', the result of
     `eval(str)' changes when the value of `x' changes.

     Unlike its prominent place in some matrix programming languages,
     `eval' is rarely necessary in Algae.  Most examples of its use are
     rather contrived.  Here's some code which evaluates an expression
     typed in by the user:

          x = eval (read ("!echo -n \"expression?  \" 1>&2 ; head -1"))

     One use for `eval' that may not be quite so contrived involves
     building a function within a function--something that you can't do
     directly in Algae.  Here's an example:

          add_const = function (c)
          {
            return eval (sprintf ("function (x) { return x+%g; }"; c));
          };

     This could then be used as follows:

          > ten_more = add_const( 10 );
          > ten_more(1)?
                  11

     Probably the most common mistake made with `eval' is giving it a
     statement instead of an expression.  If that's really what you
     want to do, use the `exec' function instead.

     Remember, too, that all variable references are at global scope.
     For example, the function

          function( a; b ) { return eval( "a + b" ); }

     returns the sum of the global variables `a' and `b'; it completely
     ignores the function's arguments, as they are local variables.

     See also `exec'.


File: algae.info,  Node: exception,  Next: exec,  Prev: eval,  Up: Execution

 - Function: exception ( )
     This function "raises an exception", meaning that Algae makes an
     error return.  If execution is interactive, control returns to the
     user.  Otherwise, Algae exits.


File: algae.info,  Node: exec,  Next: exit,  Prev: exception,  Up: Execution

 - Function: exec ( s )
     The `exec' function causes Algae to parse and execute the Algae
     statements contained in the character string S.  Execution begins
     at global scope, even if `exec' is called from a function.  It
     returns a negative integer if an error occurs, and zero otherwise.

     See also `eval' and `source'.


File: algae.info,  Node: exit,  Next: file,  Prev: exec,  Up: Execution

 - Function: exit ( status )
     This function terminates Algae.  The optional argument STATUS
     specifies the exit status that Algae returns.  On most computer
     platforms, the exit status is expected to be a small, positive
     integer.  The STATUS argument to `exit' should be numeric scalar.
     If `exit' is called with anything else, Algae returns 0 as its exit
     status.

     A call to `exit' is not mandatory in your Algae programs.  Algae
     terminates when it reaches the end of its input, returning exit
     status 0.  If an error causes Algae to terminate, exit status 1 is
     returned.


File: algae.info,  Node: file,  Next: get_path,  Prev: exit,  Up: Execution

 - Function: file ( )
     The `file' function returns the name of the file from which
     statements are currently being executed.


File: algae.info,  Node: get_path,  Next: getenv,  Prev: file,  Up: Execution

 - Function: get_path ( env; def )
     The `get_path' function returns a path list, for use in file
     searching.  The argument ENV, if it isn't NULL, gives the name of
     an environment variable containing a colon-separated list of
     paths.  The DEF argument gives a default value, in case ENV isn't
     given or doesn't exist.

     See also `search_path' and `src'.


File: algae.info,  Node: getenv,  Next: line,  Prev: get_path,  Up: Execution

 - Function: getenv ( ename )
     The `getenv' function returns a character scalar that contains the
     value of the environment variable named by ENAME.  If no such
     variable exists, NULL is returned.


File: algae.info,  Node: line,  Next: provide,  Prev: getenv,  Up: Execution

 - Function: line ( )
     The `line' function returns the line number from which it is
     called.


File: algae.info,  Node: provide,  Next: require,  Prev: line,  Up: Execution

 - Function: provide ( feature )
     A "feature" is simply a name that stands for a particular
     collection of functions or other entities.  A program announces
     that a feature is present by calling the `provide' function with
     FEATURE, the name of that feature.  This means that the facilities
     associated with FEATURE have been made available for other Algae
     programs.

     Programs that require a particular feature can source the
     appropriate file with the `require' function.

     The argument FEATURE must be a character scalar.  It is added to
     the global variable `$features' if it is not already present in
     that vector.  The `provide' function returns FEATURE.


File: algae.info,  Node: require,  Next: search_path,  Prev: provide,  Up: Execution

 - Function: require ( feature; filename )
     A "feature" is simply a name that stands for a particular
     collection of functions or other entities.  A program that needs
     the collection may ensure that they are defined by calling
     `require' with the name of that feature.  The use of named
     features simplifies the task of determining whether required
     assignments have been made.

     The `require' function checks for the feature named FEATURE in the
     current Algae session; if it isn't present, then `require' reads
     the source file FILENAME with `src'.  If FILENAME is `NULL', then
     the value of FEATURE is used as the file name.

     Before it finishes, the source file read by `require' is expected
     to call the `provide' function, indicating that the desired feature
     has been provided.  An exception is raised if the source file
     cannot be read or does not provide the feature named FEATURE.


File: algae.info,  Node: search_path,  Next: source,  Prev: require,  Up: Execution

 - Function: search_path ( fn; suffices; path )
     The `search_path' function searches for a file in the directories
     named in PATH.  The file name begins with the string given by FN,
     with one of the suffices given by SUFFICES.


File: algae.info,  Node: source,  Next: sources,  Prev: search_path,  Up: Execution

 - Function: source ( fname )
     This function causes Algae to parse and execute the file named
     FNAME.  Execution begins at global scope, even if `source' is
     called from a function.  It returns NULL if it has a problem
     opening FNAME, a negative integer if a parse or run time error
     occurs, and zero otherwise.

     The file is closed after it is read.

     See also `exec' and `sources'.


File: algae.info,  Node: sources,  Next: src,  Prev: source,  Up: Execution

 - Function: sources ( fname )
     The `sources' function causes Algae to parse and execute specified
     files.  The character scalar FNAME is passed through sh(1) to
     ls(1), so file name generation is available and multiple names may
     be given.  For example,

          sources( "*.A" );

     sources all of the files ending with `.A' in your working
     directory.  Although you could use the `source' function to do this
     as

          source( "!cat *.A" );

     using `sources' is preferable because it maintains the correct file
     and line information for the interpreter.

     The "pipe" capability normally available to Algae I/O functions is
     not permitted in `sources'.  Command substitution works, though, as
     demonstrated here:

          sources( "`find $HOME -name '*.A' -print`" );

     This example sources every file ending with `.A' found in any
     subdirectory under your home directory.


File: algae.info,  Node: src,  Next: strip,  Prev: sources,  Up: Execution

 - Function: src ( filename )
     The `src' function finds and opens a file of Algae code, executes
     the statements within it at global scope, and then closes the file.
     This function, rather than `source' or `sources', is intended to
     be the normal way to source files directly.  Other functions that
     may be used to source files are `require' and `autosrc'.

     To find the file, `src' looks first for a file named `FILENAME.A',
     that is, it appends `.A' to the name given by the argument
     FILENAME.  If a file with that name exists, it is sourced;
     otherwise, `src' looks for a file named FILENAME with nothing
     appended, and sources it if it exists.

     If FILENAME is a relative file name, such as `foo' or `foo/bar.A',
     `src' searches for the file using the variable `$src_path'.  It
     appends FILENAME to each of the directories listed in the
     character vector `$src_path' (both with and without the `.A'), and
     sources the first file it finds whose name matches.  The current
     default directory is tried only if it is specified in `$src_path'.

     No directory searching is performed if FILENAME is an absolute
     file name.  File names that begin with `/', `./', `../', or `~/'
     are absolute.  If the file name begins with `~/', the tilde is
     replaced with the value of the `HOME' environment variable.

     A file name that begins with the `!' character is a pipe; the rest
     of the file name is given as a command line to the shell, the
     standard output of which is then read by `src'.  For example,

          src("!m4 foo.A")

     runs the file `foo.A' through the `m4' macro preprocessor first
     before `src' reads it.

     The `$src_path' vector is initialized from the environment variable
     `ALGAE_SRC_PATH', if it exists.  It may be modified in either of
     the startup files `/usr/local/lib/algae/4.3.6/algae.A' or
     `$HOME/.algae'.  (*Note Startup Files::.)

     The syntax of `ALGAE_SRC_PATH' is the same as that of `PATH' for
     the shell; fields are separated by `:', and `.' is used for the
     current default directory.  To set `ALGAE_SRC_PATH' in the Bourne
     shell, type something like the following:

          export ALGAE_SRC_PATH
          ALGAE_SRC_PATH=.:~/algae:/usr/local/lib/algae

     Execution of the Algae code in FILENAME begins at global scope.
     For example, if the source file contains the single statement
     `x=1', the assignment is made to the global variable X regardless
     of whether `src' was called from within a function or not.

     The `src' function raises an exception if FILENAME cannot be
     found. It returns `NULL' if it cannot be opened, a negative integer
     if a parse or run-time error occurs, and 0 otherwise.


File: algae.info,  Node: strip,  Next: system,  Prev: src,  Up: Execution

 - Function: strip ( f )
     The `strip' function removes all file and line information from the
     given function F.  The parser ordinarily includes this information
     so that, for example, run-time error messages can identify the
     line on which they occurred.  If an error occurs in a function
     that has been stripped, then the error is attributed instead to
     the calling expression.

     This function may also be useful in conjunction with profiling.
     Any time spent in a call to a stripped function gets charged to
     the file and line from which it was called.

     All members of F are left unchanged as members of the return value.


File: algae.info,  Node: system,  Prev: strip,  Up: Execution

 - Function: system ( s )
     This function passes the string S to the command processor for
     execution.  On a UNIX system, for example, the statement
     `system("ls")' lists the files in the current directory.  If the
     call succeeds, the exit status is returned; otherwise a -1 is
     returned.


File: algae.info,  Node: Special Tools,  Next: Miscellaneous,  Prev: Execution,  Up: Standard Functions

Special Tools
=============

* Menu:

* npsol::	nonlinear optimization
* plot::	plot curves
* replot::      modify a plot
* splot::       plot surfaces
* umin::        unconstrained minimization
* unplot::      terminate plots


File: algae.info,  Node: npsol,  Next: plot,  Prev: Special Tools,  Up: Special Tools

 - Function: npsol ( objective; start; constraints; options; state )
     The `npsol' function uses a sequential quadratic programming method
     to minimize a given objective function subject to given
     constraints.  The domain of the objective function is called the
     "design space", and the coordinates of the design space are called
     "design variables".

     This function uses the NPSOL package of Fortran routines developed
     and sold by Stanford University.  Your version of Algae might not
     have the `npsol' builtin function; if not, it probably means that
     you don't have a license for NPSOL or that there was some problem
     installing it on your computer.

     The `npsol' function may not be called recursively.

     The OBJECTIVE argument may be either a function or a table.  If a
     function, then it's assumed to take one argument, a vector of
     design variables, and return the value of the objective at that
     point.  If OBJECTIVE is a table, it may have the following members:

    `objf'
          A function that returns the value of the objective function
          for the vector of design variables given as its first
          argument.  If the member `params' exists in OBJECTIVE, then
          it is passed as a second argument to `objf'.

    `objgrd'
          A function that returns the sensitivities of the objective
          function; that is, the first derivatives with respect to the
          design variables.  Its arguments are the same as for `objf'.

    `params'
          This member, if it exists, is passed as the second argument to
          `objf' and `objgrd', providing a means for passing additional
          parameters to those functions.

     Only the `objf' member is required.  If the objective derivatives
     are not provided, you must ensure that `derivative_level' is set
     accordingly.

     The START argument is a vector that specifies the starting point.

     The CONSTRAINTS argument is a table that may contain any of all of
     the following members:

    `side_constraints'
          A matrix that specifies upper and lower constraints on values
          of the design variables.  This matrix has two columns, the
          first column giving lower bounds and the second column giving
          upper bounds.  If this member is not given, then a default is
          provided using 1.0E10 as "infinity".  In that case, you
          should be aware that NPSOL will take these values literally
          if you also use the "infinite_bound" option (in OPTIONS) with
          a value greater than 1.0E10.

    `linear_constraints'
          A table that may contain any or all of the following members:

         `coefficients'
               A matrix of the linear constraint coefficients.  The
               i-th row contains the coefficients for the i-th linear
               constraint.

         `bounds'
               A matrix, like `side_constraints', that gives the upper
               and lower bounds for the linear constraints.  If not
               given, defaults are provided as with `side_constraints'.

    `nonlinear_constraints'
          A table that may contain any or all of the following members:

         `values'
               Either a function that computes the vector of nonlinear
               constraint function values at the given point, or a
               table in which member `conf' is a function returning the
               values and `congrd' is a function returning the
               gradients.  The constraint gradients, if provided,
               should be given as a matrix in which the rows correspond
               to the constraints and the columns correspond to the
               design variables.  As in OBJECTIVES, a member called
               `params' may also be included.

         `bounds'
               A matrix, like `side_constraints', that gives the upper
               and lower bounds for the nonlinear constraints.  If not
               given, defaults are provided as with `side_constraints'.

          If the constraint derivatives are not provided, you must
          ensure that `derivative_level' is set accordingly.

          The OPTIONS argument is a table that may contain any of the
          valid NPSOL options.  For example, `{ hessian = "yes" }'
          specifies the corresponding option in NPSOL.  Use an
          underscore instead of blanks between words, as in `{
          major_print_level = 1 }'.  The valid options are:

         `central_difference_interval'
               If the algorithm switches to central differences because
               the forward-difference approximation is not sufficiently
               accurate, this value is used as the difference interval
               for every variable.

         `cold_start'
         `warm_start'
               These flags control the specification of the initial
               working set in both the procedure for finding a feasible
               point for the linear constraints and bounds, and in the
               first QP subproblem thereafter.  With a `cold_start',
               the first working set is chosen by `npsol' based on the
               values of the variables and constraints at the initial
               point.  Broadly speaking, the initial working set will
               include equality constraints and bounds or inequality
               constraints that violate or "nearly" satisfy their
               bounds within `crash_tolerance'.  With a `warm_start',
               the user must provide the `state' table.  A warm start
               will be advantageous if a good estimate of the initial
               working set is available--for example, when `npsol' is
               called repeatedly to solve related problems.

         `crash_tolerance'
               This value is used in conjunction with the optional
               parameter `cold_start', which is the default.  When
               making a cold start, the QP algorithm in `npsol' must
               select an initial working set.  The initial working set
               will include, if possible, bounds or general inequality
               constraints that lie within `crash_tolerance' of their
               bounds.  The default value is 0.01.  If
               `crash_tolerance' is less than zero or greater than one,
               the default value is used.

         `derivative_level'
               This value indicates which objective and constraint
               derivatives are provided by the user.  The choices are
               as follows:

              `0'
                    Neither objective nor constraint derivatives are
                    provided.

              `1'
                    The objective derivatives are provided by the
                    `objgrd' function in argument OBJECTIVE.
                    Constraint derivatives are not provided.

              `2'
                    The nonlinear constraint derivatives are provided
                    by the `congrd' function in argument CONSTRAINTS.
                    Objective derivatives are not provided.

              `3'
                    The objective derivatives are provided by the
                    `objgrd' function in argument OBJECTIVE, and the
                    nonlinear constraint derivatives are provided by
                    the `congrd' function in argument CONSTRAINTS.

               The value 3 is the default, and should be used whenever
               possible, since `npsol' is more reliable and will
               usually be more efficient when all derivatives are exact.

               If `derivative_level' is 0 or 2, `npsol' will estimate
               the objective gradients using finite differences.  The
               computation of finite-difference approximations usually
               increases the total run time, since a call to the
               objective function is required for each constraint.
               Furthermore, less accuracy can be attained in the
               solution.

               If `derivative_level' is 0 or 1, `npsol' will
               approximate the constraint gradients.  One call to the
               constraint function is required for each variable.  At
               times, central differences are used rather than forward
               differences, in which case twice as many calls to the
               objective and constraint functions are needed.  The
               switch to central differences is not under the user's
               control.

         `difference_interval'
               This value defines an interval used to estimate
               gradients by finite differences in the following
               circumstances: (1) for verifying the objective and
               constraint gradients, and (2) for estimating the
               objective or constraint derivatives.  If a difference
               interval is not specified by the user, a finite
               difference interval will be computed automatically for
               each variable by a procedure that requires up to six
               calls of the objective and constraint functions for each
               component.  This option is recommended if the function
               is badly scaled or the user wishes to have `npsol'
               determine constant elements in the objective and
               constraint gradients.

         `feasibility_tolerance'
               This value defines the maximum acceptable absolute
               violations in linear and nonlinear constraints at a
               "feasible" point; i.e., a constraint is considered
               satisfied if its violation does not exceed this value.
               The default value is the square root of machine
               precision.

         `function_precision'
               This value is intended to be a measure of the accuracy
               with which the objective and constraint functions can be
               computed.  It acts as a relative precision when the
               magnitude is large, and as an absolute precision when
               the magnitude is small.  For example, if the objective
               function is typically on the order of 1000 and the first
               6 digits are known to be correct, then
               `function_precision' should be set to 1.0E-6. In
               contrast, if the objective function is typically on the
               order of 1.0E-4 and the first 6 digits are known to be
               correct, then `function_precision' should be set to
               1.0E-10.  The choice of `function_precision' can be
               quite complicated for badly scaled problems.  The
               default value is machine precision raised to the 0.9
               power; this is appropriate for most simple functions
               that are computed with full accuracy.  However, when the
               accuracy of the computed function values is known to be
               significantly worse than full precision, then
               `function_precision' should be large enough that `npsol'
               will not attempt to distinguish between function values
               that differ by less than the error inherent in the
               calculation.

         `hessian'
               This option must be either `"yes"' or `"no"'.  (The
               default is `"no"').  This option controls the contents
               of the `R' matrix in STATE.  The user should set
               `hessian' to `"yes"' if the `state' table returned is to
               be used for a subsequent warm start.

         `infinite_bound_size'
               If this value is greater than zero, it defines the
               "infinite" bound in the definition of the problem
               constraints.  Any upper bound greater than or equal to
               this value will be regarded as positive infinity.  Any
               lower bound less than or equal to the negative of this
               value will be regarded as negative infinity.  The
               default value is 1.0E10.

         `infinite_step_size'
               This value specifies the magnitude of the change in
               variables that is treated as a step to an unbounded
               solution.  If the change in any variable during an
               iteration would exceed the value of
               `infinite_step_size', the objective function is
               considered to be unbounded below in the feasible region.
               The default is the greater of `infinite_bound_size' and
               1.0E10.

         `iteration_limit'
               This value specifies the maximum number of major
               iterations allowed before termination.

         `linear_feasibility_tolerance'
         `nonlinear_feasibility_tolerance'
               These values define the maximum acceptable absolute
               violations in linear and nonlinear constraints at a
               "feasible" point.  A constraint is considered satisfied
               if its violation does not exceed this value.  The
               default value for both options is the square root of
               machine precision.

               On entry to `npsol', an iterative procedure is executed
               in order to find a point that satisfies the linear
               constraints and bounds on the variables to within
               `linear_feasibility_tolerance'.  All subsequent iterates
               will satisfy the linear constraints to within the same
               tolerance, unless this value is comparable to the finite
               difference interval.

               For nonlinear constraints,
               `nonlinear_feasibility_tolerance' defines the largest
               constraint violation that is acceptable at an optimal
               point.  Since nonlinear constraints are generally not
               satisfied until the final iterate, this value acts as a
               partial termination criterion for the iterative sequence.

               These tolerances should reflect the precision of the
               corresponding constraints.  for example, if the
               variables and the coefficients in the linear constraints
               are of order unity, and the latter are correct to about
               6 decimal digits, it would be appropriate to specify
               `linear_feasibility_tolerance' as 1.0E-6.

         `linesearch_tolerance'
               This value controls the accuracy with which a step taken
               during each iteration approximates a minimum of the
               merit function along the search direction.  The smaller
               the value, the more accurate the line search.  The
               default value is 0.9; it requests an inaccurate search
               that is appropriate for most problems, particularly
               those with any nonlinear constraints.

               If there are non nonlinear constraints, a more accurate
               search may be appropriate when it is desirable to reduce
               the number of major iterations--for example, if the
               objective function is cheap to evaluate or if the
               gradients are not specified.

         `list'
               If this flag is given, all of the options and their
               values are printed.

         `print_level'
               This value controls the amount of printed output
               produced by the major iterations of `npsol'.  The levels
               are as follows:

              `0'
                    No output.  This is the default.

              `1'
                    The final solution only.

              `5'
                    One line of output for each major iteration, but no
                    final solution.

              `10'
                    The final solution and one line of output for each
                    iteration.

              `20'
                    At each major iteration, the objective function,
                    the Euclidean norm of the nonlinear constraint
                    violations, the value of the nonlinear constraints,
                    the values of the linear constraints, and the
                    current values of the variables.

         `minor_iteration_limit'
               This value specifies the maximum number of iterations
               for the optimality phase of each QP subproblem.

         `minor_print_level'
               This value controls the amount of printout produced by
               the minor iterations of `npsol'.  The levels are as
               follows:

              `0'
                    No output.  This is the default.

              `1'
                    The final QP solution.

              `5'
                    One line of output for each minor iteration, but no
                    final QP solution.

              `10'
                    The final QP solution and one line of output for
                    each minor iteration.

              `20'
                    At each minor iteration, the current estimates of
                    the QP multipliers, the current estimate of the QP
                    search direction, the QP constraint values, and the
                    status of each QP constraint.

         `optimality_tolerance'
               This value specifies the accuracy to which the user
               wishes the final iterate to approximate a solution of
               the problem.  Broadly speaking, it indicates the number
               of correct figures desired in the objective function at
               the solution.  For example, if `optimality_tolerance' is
               1.0E-6 and `npsol' terminates successfully, the final
               value of the objective function should have
               approximately 6 correct figures.  The `npsol' function
               will terminate successfully if the iterative sequence is
               judged to have converged and the final point satisfies
               the first-order optimality conditions.

         `verify_level'
               This value refers to finite-difference checks on the
               gradients computed by the user function `objgrd' and
               `congrd'.  It may take on one of the following values:

              `-1'
                    No checks are made.

              `0'
                    Perform only a very inexpensive check, involving
                    one call to the objective function and one call to
                    the constraint function.

              `1'
                    Perform a reliable but expensive check on the
                    objective gradients.

              `2'
                    Perform a reliable but expensive check on the
                    constraint gradients.

              `3'
                    Perform reliable but expensive checks on both the
                    objective and the constraint gradients.

               These checks are recommended whenever a new function
               routine is being developed.

          The STATE argument is used only when the NPSOL "warm_start"
          option is requested.  It may be obtained from the return of a
          previous call to `npsol'.  Its members are:

         `ISTATE'
               A vector describing the status of the constraints.

         `CLAMDA'
               The Lagrange multiplier estimates for the nonlinear
               constraints.

         `R'
               The factored Hessian of the Lagrangian function.

          The `npsol' function returns a table containing the following
          members:

         `objective'
               The value of the objective function at the final iterate.

         `solution'
               The solution vector (or final estimate) for the problem.

         `inform'
               The INFORM value (success/error indicator) returned by
               NPSOL.  The possibilities are:

              `0'
                    The iterates have converged to a point that
                    satisfies the first-order optimality conditions to
                    the accuracy requested by the optional parameter
                    `optimality_tolerance', i.e., the projected
                    gradient and active constraint residuals are
                    negligible.  (Success.)

              `1'
                    The final iterate satisfies the first-order
                    optimality conditions to the accuracy requested,
                    but the sequence of iterates has not yet converged.
                    NPSOL was terminated because no further improvement
                    could be made in the merit function.  (Probable
                    success.)

              `2'
                    No feasible point could be found for the linear
                    constraints and bounds.  The problem has no
                    feasible solution.

              `3'
                    No feasible point could be found for the nonlinear
                    constraints.  The problem may have no feasible
                    solution.

              `4'
                    The limiting number of iterations, determined by
                    the optional parameter `major_iteration_limit', has
                    been reached.

              `6'
                    The current point does not satisfy the first-order
                    optimality conditions, and no improved point for
                    the merit function could be found during the final
                    line search.

              `7'
                    The user-provided derivatives of the objective
                    function and/or nonlinear constraints appear to be
                    incorrect.

              `9'
                    An input parameter is invalid.

         `iter'
               The number of major iterations performed.

         `state'
               The `state' table described above.


File: algae.info,  Node: plot,  Next: replot,  Prev: npsol,  Up: Special Tools

 - Function: plot ( ... )
     The `plot', `splot', `replot', and `unplot' functions provide an
     interface to the gnuplot program for plotting data.  Use `plot'
     for plotting lines in two or three dimensions; `splot' is for
     plotting surfaces in three dimensions.

     To use these plotting functions effectively, you will probably
     need some familiarity with the gnuplot commands.  For example, to
     add a title to an existing plot, you'd type something like
     `replot("set title 'Good Stuff'")'.  Read the gnuplot manual or
     its on-line help for more information.

     The `plot' function accepts as many as three arguments.  If either
     or both of the first two arguments are (or can be converted to)
     character vectors, then their elements are sent, each on a separate
     line, to gnuplot as commands.  For example, `plot("set term X11")'
     causes gnuplot to generate X11 output.  Even commands that request
     information from gnuplot, like `plot("show term")' are acceptable
     (although you might temporarily lose sight of Algae's prompt).
     Don't use the "exit" or "quit" commands of gnuplot--they cause
     gnuplot to exit without Algae knowing about it.

     If more than one argument is given to `plot' and the last one is an
     integer scalar, then it is taken to be an identifier for the plot
     process.  This allows you to have more than one plot open at a
     time.  If no identifier is given, then the active plot is killed
     and replaced by a new one with the same identifier.  The "active"
     plot is the one last referenced, or 1 if there are no plots open.
     The `replot' function may be used to modify an open plot.

     Any other arguments given to `plot' are taken to be data to be
     plotted.  Vectors are plotted using their element values as
     ordinates and their labels for the abscissae.  Matrices with 2
     columns are plotted using the second column for ordinates and the
     first column for abscissae.  A matrix with 3 columns is plotted as
     a curve in three dimensions, with the third column specifying the
     ordinates.  Surface plots are obtained using the `splot' function.

     If the data given to `plot' is a vector, but has no labels, then
     the element indices are used instead of the labels.

     Multiple curves may be shown on the same plot, either by giving
     `plot' two data arguments or (better yet) supplying the data in a
     table.  When data is given in a table (even if it contains only one
     member), the member name is used in the plot legend.  Otherwise,
     `plot' uses the names "y_1" and "y_2".

     If the data is given in a table, any members that are tables
     themselves are given to gnuplot in a single data file.  This means
     that the same line and point type is used.  For example, if `x'
     and `y' are vectors to be plotted, then `plot({x;y})' plots the
     two, each with a different line and point type and described by
     name in the legend.  On the other hand, `plot({z={x;y}})' plots
     them with the same line and point type and names the combination
     "z" in the legend.

     If `plot' is called with no arguments, it returns a vector of the
     open plot identifiers.  This vector is sorted from most to least
     recently referenced, so the "active" plot is first.

     Here's an example that simulates the Van der Pol system and plots
     the results:

          xdot = function( t; x ) {
              return x[1]*(1-x[2]^2)-x[2], x[1];
          }
          x = ode4( xdot; 0; 20; 0,.25 );
          plot( "set data style lines"; { x1=x[1;]; x2=x[2;] } );

     See also `splot', `replot', and `unplot'.


File: algae.info,  Node: replot,  Next: splot,  Prev: plot,  Up: Special Tools

 - Function: replot ( ... )
     The `replot' function is used to modify or redisplay plots created
     with either the `plot' or `splot' functions.  It takes at most 2
     arguments.  If the first argument has character type, it is passed
     to gnuplot as commands.

     The last argument is the optional plot identifier.  If not given,
     the active plot is used by default.

     See also `plot', `splot', and `unplot'.


File: algae.info,  Node: splot,  Next: umin,  Prev: replot,  Up: Special Tools

 - Function: splot ( ... )
     The `splot' function is used to plot surfaces in three dimensions.
     Except for the form of the data, its input is identical to that of
     the `plot' function.  The data is specifed as a matrix of
     ordinates.  The labels of the matrix, or the corresponding indices
     if the labels don't exist, are used for the abscissae.

     See also `plot', `replot', and `unplot'.


File: algae.info,  Node: umin,  Next: unplot,  Prev: splot,  Up: Special Tools

 - Function: umin ( objective; start; options )
     The `umin' function performs unconstrained minimization using the
     Nelder-Mead direct search method.  It does not have the features or
     sophistication of `npsol', but it works well for some
     cases--particularly when the objective surface is not smooth.

     The OBJECTIVE argument is a function that takes one or two
     arguments and returns the value of the objective at that point.
     The first argument is a vector of design variables.  The second
     argument, which is optional, is passed unchanged from the PARAMS
     member of the OPTIONS argument to `umin' itself.

     The START argument is an integer or real vector that specifies the
     starting point.

     The OPTIONS augument may be either NULL or a table containing
     convergence and other specifications.  The meaningful options are:

    `bound'
          The minimum value permitted for the objective function.  The
          default is -1e32.

    `display'
          A function called at each "successful" iteration with the
          current design point as its only argument.  This may be used,
          for example, to plot the design as it changes.

    `evals'
          The maximum number of objective function evaluations
          permitted.  The default value is 1000.

    `iter'
          The maximum number of iterations permitted.  The default
          value is 100.

    `params'
          The value of this member is passed as the second argument to
          the objective function.

    `right'
          If this member exists, then the initial simplex has right
          angles.  By default, the initial simplex has sides of equal
          length.

    `size'
          The initial size of the simplex.  By default, this is the
          greater of 1 and the infinity norm of the starting vector.

    `tol'
          The relative size of the simplex, below which the iteration
          is taken to have converged.  The tolerance is 1e-6 by default.

    `verbose'
          If this member exists, then information is printed at each
          "successful" iteration.

     The return value from `umin' is a table with the following members:

    `evals'
          The number of objective function evaluations.

    `inform'
          A return code specifying success or failure:

         `0'
               success

         `1'
               failure, objective bound reached

         `2'
               failure, function evaluation limit exceeded

         `3'
               failure, iteration limit exceeded

    `iter'
          The number of iterations performed.

    `msg'
          A message corresponding to the inform code.

    `obj'
          The final objective value.

    `sol'
          The final design point.

     This code is based on `nmsmax', a MATLAB function by Nick Higham.

     See also `npsol'.


File: algae.info,  Node: unplot,  Prev: umin,  Up: Special Tools

 - Function: unplot ( id )
     The `unplot' function is used to terminate plots created with the
     `plot' or `splot' functions.  The integer scalar or vector
     argument ID specifies the identifiers of the plots to be
     terminated.  If no ID is given, the active plot is terminated.
     You can terminate all open plots with `unplot(plot())'.

     See also `plot', `replot', and `splot'.


File: algae.info,  Node: Miscellaneous,  Prev: Special Tools,  Up: Standard Functions

Miscellaneous
=============

* Menu:

* all::         test all elements
* atof::        convert string to number
* char::        vector to character string
* class::	entity class
* equal::	test for equality
* members::	members of a table
* info::        documentation browsing system
* prof::        summarize profiler output
* show::	show entity information
* split::       split string into fields
* string::      convert to character type
* substr::      return a substring
* test::	truth test
* time::        user time
* tolower::     convert strings to lower case
* toupper::     convert strings to upper case
* what::	list functions
* who::		list variables


File: algae.info,  Node: all,  Next: atof,  Prev: Miscellaneous,  Up: Miscellaneous

 - Function: all ( x )
     The `all' function evaluates the "truth" of its argument X in the
     same way that the function `test' does, except that vectors and
     matrices are "true" only if all of their elements are "true".  For
     example, `all(1,0)' returns 0 while `test(1,0)' returns 1.  If X
     has no elements, `all' returns 0.

     See also `test' and `equal'.


File: algae.info,  Node: atof,  Next: char,  Prev: all,  Up: Miscellaneous

 - Function: atof ( s )
     The `atof' function converts character strings to real numbers.
     The argument S may be a scalar, vector, or matrix.  The function
     reads only up to the first unrecognized character of each string,
     and ignores anything that remains.  If the first character of a
     string is unrecognized, then the value is taken to be zero.


File: algae.info,  Node: char,  Next: class,  Prev: atof,  Up: Miscellaneous

 - Function: char ( v )
     The `char' function converts the vector V into a character string;
     each element of V contributes a single character according to its
     ASCII value.  For example, `char(65,66,67)' returns the string
     `"ABC"'.

     If an element of V is less than 0 or greater than 255, then it
     will "wrap" (modulo 256).  Thus `char(65)' and `char(65+256)' both
     return the string `"A"'.

     Algae's character strings are terminated with a NUL (0) character.
     For the `char' function, that means that if an element of V is
     zero (or a multiple of 256) then the string is terminated at that
     point.  For example, `char(65,0,66)' yields the string `"A"'.


File: algae.info,  Node: class,  Next: equal,  Prev: char,  Up: Miscellaneous

 - Function: class ( x )
     The `class' function returns a character string (such as "scalar"
     or "table") that describes the class of X.


File: algae.info,  Node: equal,  Next: members,  Prev: class,  Up: Miscellaneous

 - Function: equal ( a; b )
     This function tests A and B for equality.  For vectors and
     matrices, it returns true (1) only if every pair of corresponding
     elements is equal, and false (0) otherwise.  For all other
     classes, this function returns the same value as the expression
     `a==b' would.

     See also `test'.


File: algae.info,  Node: members,  Next: info,  Prev: equal,  Up: Miscellaneous

 - Function: members ( e )
     This function returns a vector containing the names of the members
     of E.


File: algae.info,  Node: info,  Next: prof,  Prev: members,  Up: Miscellaneous

 - Function: info ( topic )
     This function starts up an interactive browser for Algae's
     documentation.  The optional argument TOPIC (a character scalar)
     takes you directly to that topic.  For example, `info("sort")'
     takes you directly to the description of the `sort' function.

     If possible, `info' uses an X-based html browser (like netscape or
     mosaic).  Otherwise, a character-based html browser (like lynx)
     will be tried.  As a final resort, the GNU Info browser is called.

     The names of the available browsers are assigned by the startup
     code (*note Startup Files::) as members `xhtml', `html', and
     `info' of the global table `$programs'.  To prevent Algae from
     using a particular browser, simply set the appropriate member of
     `$programs' to a zero-length string.  If you prefer to use Info,
     for example, you could simply put the line

          $programs.xhtml = $programs.html = "";

     in your `.algae' file.

