6. The Standard Functions

Functions are called by giving their name followed by a parenthesized list of their arguments. For example, sqrt(a) computes the square root of its argument `a'. The parentheses are required, whether they contain any arguments or not. Functions may take more than one number and kind of argument.

6.1 Basic Math    abs, sin, sqrt, ...

6.2 Arrays    fill, sparse, zero, ...

6.3 Sets    union, intersection, ...

6.4 Linear Algebra    solve, factor, fft, ...

6.5 Numerical Analysis    ode4, brent, ...

6.6 Basic I/O    read, printf, ...

6.7 Entity I/O    get, put, ...

6.8 Execution    source, system, ...

6.9 Special Tools    plot, npsol, ...

6.10 Miscellaneous    who, what, time, ...

6.1 Basic Math

Function: abs ( x )

The abs function returns the absolute value of its numeric argument. "Absolute value" is synonymous with "magnitude" for complex types. If x is non-scalar, every element is replaced by its absolute value.

x must be a numeric scalar, vector, or matrix.

Function: acos ( x )

The acos function returns the arc cosine of its numeric argument. If it's argument is complex or has a magnitude greater than one, then the result is complex. Otherwise, the result is real. If x is non-scalar, every element is replaced by its arc cosine.

The argument x must be a numeric scalar, vector, or matrix.

Function: acosh ( x )

The acosh function returns the hyperbolic arc cosine of its numeric argument. If it's argument is complex or is less than 1.0, then the result is complex. Otherwise, the result is real. If x is non-scalar, every element is replaced by its hyperbolic arc cosine.

The argument x must be a numeric scalar, vector, or matrix. Note that acosh(0) is not zero, so if acosh is applied to a sparse vector or matrix, then a dense array is the result.

Function: arg ( z )

The arg function returns the argument (phase angle) of its numeric argument.

6.2 Arrays

Function: band ( m )

The band function computes the upper and lower bandwidths and profiles of the square matrix m. The row bandwidth of a particular row is the number of elements to the left of the diagonal in that row, but not including any consecutive zero elements at the beginning of that row. Likewise, the column bandwidth of a particular column is the number of elements above the diagonal in that column, but not including any consecutive zero elements at the beginning of that column. Notice that, for a diagonal matrix, all row and column bandwidths are zero. The lower bandwidth is the largest of all the row bandwidths, and the upper bandwidth is the largest of all the column bandwidths. The lower profile is the sum of all the row bandwidths, and the upper profile is the sum of all the column bandwidths.

This function returns a real vector with four elements. In order, these elements are as follows: lower bandwidth, lower profile, upper bandwidth, and upper profile.

Profile reduction can be very effective in reducing the time and memory required to factor a matrix. The function gpskca provides one approach for doing this.

6.3 Sets

Function: complement ( a; b )

The complement function returns the relative complement of a in b; that is, the set of elements of b which are not in a. The return value is a set, which we define as a sorted, irredundant vector. "Sorted" means sorted by increasing value; character strings are sorted by ASCII values and complex numbers are sorted with the real values as the primary key and the imaginary values as the secondary key.

If b has labels, then the returned vector also has labels that correspond to the retained elements. If b has no labels, the labels of the returned vector give the index of the corresponding element in b.

If b has redundant elements, the element retained is not necessarily the first. For example, complement(1;2,2,2).eid might be 1, 2, or 3.

See also intersection, set, and union.

Function: intersection ( a; b )

The intersection function returns the intersection of set a in b; that is, the set of elements that are in both a and b. The return value is a set, which we define as a sorted, irredundant vector. "Sorted" means sorted by increasing value; character strings are sorted by ASCII values and complex numbers are sorted with the real values as the primary key and the imaginary values as the secondary key.

The return vector has no labels.

See also complement, set, and union.

Function: set ( x )

This function changes x into a set, if possible. A "set" is defined as a sorted, irredundant vector. "Sorted" means sorted by increasing value; character strings are sorted by ASCII values and complex numbers are sorted with the real values as the primary key and the imaginary values as the secondary key. "Irredundant" means that no two elements have the same value.

If x has labels, then the returned vector also has labels that correspond to the retained elements. If x has no labels, the labels of the returned vector give the index of the corresponding element in x.

If x has redundant elements, the element retained is not necessarily the first. For example, set(1,1,1).eid might be 1, 2, or 3.

See also complement, intersection, and union.

Function: union ( a; b )

The union function returns the union of sets a and b. The return value is a set, which we define as a sorted, irredundant vector. "Sorted" means sorted by increasing value; character strings are sorted by ASCII values and complex numbers are sorted with the real values as the primary key and the imaginary values as the secondary key.

The return vector will always have labels. To understand them, you need to know that the function call union(a;b) is identical to the code set(a,b) provided that a and b are both vectors. (The union function will convert them both to vectors if necessary.)

See also complement, intersection, and set.

6.4 Linear Algebra

Function: backsub ( afac; b )

The backsub function solves the set of linear equations A*x=b for x. (Despite the name, it does both forward and backward substitution.) The argument afac must contain the factorization of A returned as a table from either of the functions factor or chol. The argument b provides the right-hand side.

This function handles both LAPACK (dense) and SuperLU (sparse) factors. It determines the appropriate solution method based on the members in the afac table.

If BCSLIB-EXT (a sparse math library produced by Boeing Computer Services) is available on your system and Algae has been compiled for it, then the backsub function can use it. If afac contains factors computed by BCSLIB-EXT routines (in factor or chol), then backsub will call the corresponding routines to perform the back substitution.

6.5 Numerical Analysis

Function: brent ( f; a; b; tol; param ): This function uses Brent's method to find a single root of the function f; that is, a solution to f(x)=0. The ordinates A and B must bracket a root, meaning that f(A)*f(B) must be negative. If param is given, it is passed as the second argument to the function f.

Function: monte ( f; limits; tol )

This function uses the Monte Carlo method to integrate a function. The function values are obtained by calling the function f with one vector argument. The matrix limits describes the rectangular region over which the function is integrated. It has two columns and as many rows as f has dimensions. Each row specifies the extremes of the region for the corresponding dimension.

The tol argument specifies an error tolerance. (This argument is required: there is no default.) There is no limit to the number of points chosen; monte continues to pick points until its one standard deviation error estimate is less than tol. Generally, the accuracy increases only as the square root of the number of points evaluated.

The Monte Carlo method provides a simple, easy approach for solving (numerically) even complicated, multi-dimensional integrals. However, it is notoriously inefficient. Each additional digit of accuracy requires 100 times more effort.

Here is a simple example, in which we compute the area of a circle with unit radius. With domain, we specify a square centered on the origin within which to integrate. The number of independent variables in the problem (2 in this case) is determined by the number of rows of domain. The function f takes as its argument a vector of the independent variables and returns the function value at that point. It will be called repeatedly, with the independent variables spread randomly within the domain. For this problem, f returns 1 if the point is inside the circle, and 0 otherwise.

domain = [-1,1; -1,1]; f = function (x) { return norm(x) < 1; }; monte (f; domain; 0.1)? 3.040 monte (f; domain; 0.01)? 3.120 monte (f; domain; 0.001)? 3.142

As you can see from the results, the third call to monte gave a more accurate result, but it took 10,000 times the effort used in the first call.

By the way, this problem could be solved faster with a one-dimensional integration. Then again, we already know the answer, don't we?

Function: ode4 ( f; t0; tf; x0; y; tol; h; s )

The ode4 function uses fourth and fifth order Runge-Kutta formulas to solve an initial value problem involving a system of ordinary differential equations. The function f, called as f( t; x ), is expected to return the first derivative of the state vector x with respect to the independent variable t. The arguments t0 and tf are the initial and final values of the independent variable, and x0 is the initial state vector. The argument y may be a function, called as y( t; x ), that returns a vector of output values. If y is NULL, the output vector is the state vector itself.

The optional argument tol specifies the desired accuracy; we use 0.001 if tol is NULL. An initial stepsize may be suggested with h. The s argument may be used to provide better control over the accuracy--if s is not NULL, then a step is accepted if the estimated error in each state, divided by the corresponding term of s, is not greater than tol.

The return value is a matrix containing the output history. Each column contains the output from y for the particular value of the independent variable given by the column label.

Function: roots ( c )

This function computes the roots of the polynomial having the coefficients given by the vector c. If c has n+1 elements, the equation solved (for x) is

c[1]*x^n + c[2]*x^(n-1) + ... + c[n]*x + c[n+1] = 0

A vector with zero elements is returned if the equation has no solution (roots(1), for example). NULL is returned if it has an infinite number of solutions (roots(0), for example). Otherwise, the vector returned contains all of the solutions.

Function: spline ( a; x )

This function computes or evaluates natural cubic spline interpolations for given data. If called with one argument, a, a spline for the points in the vector a is computed. The elements of a give the ordinates; the labels of a give the abscissae. If a has no numeric labels, then the natural numbers from one to the length of a are assumed. In any case, the vector a is sorted with respect to its labels; they must be unique.

If spline is called with two arguments, a and x, then the spline a (or a spline interpolation of a, if a is not a spline) is evaluated at the abscissa values given by the vector x.

Function: trapz ( y )

This function computes an approximation of the integral of y using the trapezoidal method. If y has numeric labels, they are used as its abscissae; otherwise, unit spacing is assumed. For the result to make sense, you'll probably want the labels to be in monotonically increasing order.

As an example, use trapz to compute the definite integral of 1/x from 1 to 2.

x = linspace (1; 2; 11); y = label (1/x; x); trapz (y) 0.6938 log(2)-log(1) 0.6931

6.6 Basic I/O

Function: close ( file ): The close function closes the specified file. The file name file must be given exactly as it was when the file was opened. (Whitespace is significant.) Any buffered data is flushed.

Function: digits ( n )

The digits function may be used to specify the number of digits that Algae uses when printing real and complex numbers. This applies to the print function and to "printing statements" (those with question mark or newline terminators). The argument n specifies the number of digits. If n is NULL, no action is taken.

The function returns the number of digits being used. By default, Algae uses 4 digits.

Here's an example interaction, with user input preceded by the ">" prompt:

> digits () # the default 4 > acos (-1) # pi, to 4 significant digits 3.142 > digits (20); # set to 20 digits > acos (-1) # pi, to 20 digits (but only accurate to 17) 3.1415926535897931000

This function simply sets the global variable $digits, so you can do the same thing by assigning to it directly.

6.7 Entity I/O

Function: get ( file )

The get function reads an Algae entity from a binary file named file. If no argument is given, standard input is used. Use this function to read files written with put. The file name can specify a pipe; see fprintf for more details.

NULL is returned if an error occurs in reading the file; otherwise get returns the entity it read.

Function: getdyn ( fname )

This function reads matrices from the DYNASTY file fname. (DYNASTY is the name of a software package used at Boeing for dynamic analysis.) A table is returned, containing the matrices as members.

The file name can specify a pipe; see fprintf for more details.

Function: getmat ( fname )

The getmat function reads matrices from a MATLAB binary file named fname. It returns the matrices in a table.

The file name can specify a pipe; see fprintf for more details.

Notice that getmat doesn't assign the matrices to the global symbol table as MATLAB's "load" function does. To do that, you might use something like the following:

Load = function (fname) { local (t; n); t = getmat (fname); for (n in members (t)) { $$.(n) = t.(n); } };

The getmat function reads the MATLAB v.4 "Level-1 MAT-file" format. MATLAB can read and write in this format, but its default for writing is now Level-2. Using the newer format would require us to link to their libraries, meaning that you'd need to actually have MATLAB on that machine. We'll stick with the older format.

One unfortunate consequence of using the older file format is that matrices cannot be written in sparse form. To get around this, convert the matrix to coordinate form (which is dense) within MATLAB and then change it back to sparse form in Algae with the mksparse function.

6.8 Execution

Function: autosrc ( name; file )

This function creates an autosrc function named name. When this new function is later called, it replaces itself with a definition that it reads by calling the src function with the file name file. In this way, you can put off reading a function's definition until it is actually called.

If file is NULL, then autosrc uses the value of name for the file name.

For example, consider the following code:

autosrc ("yow"); yow ();

The first line defines an autosrc function named yow. When yow is called on the second line, it reads the real definition of yow by calling src with the file name "yow". It then calls its replacement (with the same arguments, of course).

The current implementation of autosrc restricts the number of arguments to 10. (It's an ugly restriction, but if you need that many arguments perhaps you should be using a table, instead.) A zero returned indicates success.

Function: builtin ( file; symbol )

On machines that support dymamic linking, this function creates a new builtin function by linking to a shared object named by file and locating the symbol named by symbol.

Suppose you have some old Fortran code that computes your chances of being hit by a comet. You can write a C wrapper for it, link them as a shared object, use builtin to attach it, and, voila!, it's a builtin function.

Unlike other functions in Algae that deal with files, builtin does not accept the special "bang" type file names. (These are file names that begin with an exclamation point and are given to the shell as a command.)

It isn't hard to create shared objects for builtin, but currently there's no documentation for it. Perhaps you can find some code to imitate.

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.

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.

6.9 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.

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.

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.

6.10 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.

6.1 Basic Math		abs, sin, sqrt, ...
6.2 Arrays		fill, sparse, zero, ...
6.3 Sets		union, intersection, ...
6.4 Linear Algebra		solve, factor, fft, ...
6.5 Numerical Analysis		ode4, brent, ...
6.6 Basic I/O		read, printf, ...
6.7 Entity I/O		get, put, ...
6.8 Execution		source, system, ...
6.9 Special Tools		plot, npsol, ...
6.10 Miscellaneous		who, what, time, ...