1This is algae.info, produced by makeinfo version 4.3 from algae.texinfo. 2 3INFO-DIR-SECTION Programming Languages 4START-INFO-DIR-ENTRY 5* algae: (algae). Another Matrix Programming Language 6END-INFO-DIR-ENTRY 7 8 9File: algae.info, Node: cd, Next: eval, Prev: builtin, Up: Execution 10 11 - Function: cd ( path ) 12 The `cd' function changes the current default directory to that 13 specified by the character scalar PATH. If PATH is NULL, the 14 directory is changed to that given by the `HOME' environment 15 variable. 16 17 An exception is raised if an error occurs; otherwise, `cd' returns 18 the integer 1. 19 20 21File: algae.info, Node: eval, Next: exception, Prev: cd, Up: Execution 22 23 - Function: eval ( s ) 24 The `eval' function evaluates the string S as an expression and 25 returns its value. Variable references, if any, have global scope. 26 For example, consider the following interaction: 27 28 > x = 0.5; 29 > str = "sin(x)"; 30 > eval (str) 31 0.4794 32 > x = 1.0; 33 > eval (str) 34 0.8415 35 36 Although the value of `str' remains `"sin(x)"', the result of 37 `eval(str)' changes when the value of `x' changes. 38 39 Unlike its prominent place in some matrix programming languages, 40 `eval' is rarely necessary in Algae. Most examples of its use are 41 rather contrived. Here's some code which evaluates an expression 42 typed in by the user: 43 44 x = eval (read ("!echo -n \"expression? \" 1>&2 ; head -1")) 45 46 One use for `eval' that may not be quite so contrived involves 47 building a function within a function--something that you can't do 48 directly in Algae. Here's an example: 49 50 add_const = function (c) 51 { 52 return eval (sprintf ("function (x) { return x+%g; }"; c)); 53 }; 54 55 This could then be used as follows: 56 57 > ten_more = add_const( 10 ); 58 > ten_more(1)? 59 11 60 61 Probably the most common mistake made with `eval' is giving it a 62 statement instead of an expression. If that's really what you 63 want to do, use the `exec' function instead. 64 65 Remember, too, that all variable references are at global scope. 66 For example, the function 67 68 function( a; b ) { return eval( "a + b" ); } 69 70 returns the sum of the global variables `a' and `b'; it completely 71 ignores the function's arguments, as they are local variables. 72 73 See also `exec'. 74 75 76File: algae.info, Node: exception, Next: exec, Prev: eval, Up: Execution 77 78 - Function: exception ( ) 79 This function "raises an exception", meaning that Algae makes an 80 error return. If execution is interactive, control returns to the 81 user. Otherwise, Algae exits. 82 83 84File: algae.info, Node: exec, Next: exit, Prev: exception, Up: Execution 85 86 - Function: exec ( s ) 87 The `exec' function causes Algae to parse and execute the Algae 88 statements contained in the character string S. Execution begins 89 at global scope, even if `exec' is called from a function. It 90 returns a negative integer if an error occurs, and zero otherwise. 91 92 See also `eval' and `source'. 93 94 95File: algae.info, Node: exit, Next: file, Prev: exec, Up: Execution 96 97 - Function: exit ( status ) 98 This function terminates Algae. The optional argument STATUS 99 specifies the exit status that Algae returns. On most computer 100 platforms, the exit status is expected to be a small, positive 101 integer. The STATUS argument to `exit' should be numeric scalar. 102 If `exit' is called with anything else, Algae returns 0 as its exit 103 status. 104 105 A call to `exit' is not mandatory in your Algae programs. Algae 106 terminates when it reaches the end of its input, returning exit 107 status 0. If an error causes Algae to terminate, exit status 1 is 108 returned. 109 110 111File: algae.info, Node: file, Next: get_path, Prev: exit, Up: Execution 112 113 - Function: file ( ) 114 The `file' function returns the name of the file from which 115 statements are currently being executed. 116 117 118File: algae.info, Node: get_path, Next: getenv, Prev: file, Up: Execution 119 120 - Function: get_path ( env; def ) 121 The `get_path' function returns a path list, for use in file 122 searching. The argument ENV, if it isn't NULL, gives the name of 123 an environment variable containing a colon-separated list of 124 paths. The DEF argument gives a default value, in case ENV isn't 125 given or doesn't exist. 126 127 See also `search_path' and `src'. 128 129 130File: algae.info, Node: getenv, Next: line, Prev: get_path, Up: Execution 131 132 - Function: getenv ( ename ) 133 The `getenv' function returns a character scalar that contains the 134 value of the environment variable named by ENAME. If no such 135 variable exists, NULL is returned. 136 137 138File: algae.info, Node: line, Next: provide, Prev: getenv, Up: Execution 139 140 - Function: line ( ) 141 The `line' function returns the line number from which it is 142 called. 143 144 145File: algae.info, Node: provide, Next: require, Prev: line, Up: Execution 146 147 - Function: provide ( feature ) 148 A "feature" is simply a name that stands for a particular 149 collection of functions or other entities. A program announces 150 that a feature is present by calling the `provide' function with 151 FEATURE, the name of that feature. This means that the facilities 152 associated with FEATURE have been made available for other Algae 153 programs. 154 155 Programs that require a particular feature can source the 156 appropriate file with the `require' function. 157 158 The argument FEATURE must be a character scalar. It is added to 159 the global variable `$features' if it is not already present in 160 that vector. The `provide' function returns FEATURE. 161 162 163File: algae.info, Node: require, Next: search_path, Prev: provide, Up: Execution 164 165 - Function: require ( feature; filename ) 166 A "feature" is simply a name that stands for a particular 167 collection of functions or other entities. A program that needs 168 the collection may ensure that they are defined by calling 169 `require' with the name of that feature. The use of named 170 features simplifies the task of determining whether required 171 assignments have been made. 172 173 The `require' function checks for the feature named FEATURE in the 174 current Algae session; if it isn't present, then `require' reads 175 the source file FILENAME with `src'. If FILENAME is `NULL', then 176 the value of FEATURE is used as the file name. 177 178 Before it finishes, the source file read by `require' is expected 179 to call the `provide' function, indicating that the desired feature 180 has been provided. An exception is raised if the source file 181 cannot be read or does not provide the feature named FEATURE. 182 183 184File: algae.info, Node: search_path, Next: source, Prev: require, Up: Execution 185 186 - Function: search_path ( fn; suffices; path ) 187 The `search_path' function searches for a file in the directories 188 named in PATH. The file name begins with the string given by FN, 189 with one of the suffices given by SUFFICES. 190 191 192File: algae.info, Node: source, Next: sources, Prev: search_path, Up: Execution 193 194 - Function: source ( fname ) 195 This function causes Algae to parse and execute the file named 196 FNAME. Execution begins at global scope, even if `source' is 197 called from a function. It returns NULL if it has a problem 198 opening FNAME, a negative integer if a parse or run time error 199 occurs, and zero otherwise. 200 201 The file is closed after it is read. 202 203 See also `exec' and `sources'. 204 205 206File: algae.info, Node: sources, Next: src, Prev: source, Up: Execution 207 208 - Function: sources ( fname ) 209 The `sources' function causes Algae to parse and execute specified 210 files. The character scalar FNAME is passed through sh(1) to 211 ls(1), so file name generation is available and multiple names may 212 be given. For example, 213 214 sources( "*.A" ); 215 216 sources all of the files ending with `.A' in your working 217 directory. Although you could use the `source' function to do this 218 as 219 220 source( "!cat *.A" ); 221 222 using `sources' is preferable because it maintains the correct file 223 and line information for the interpreter. 224 225 The "pipe" capability normally available to Algae I/O functions is 226 not permitted in `sources'. Command substitution works, though, as 227 demonstrated here: 228 229 sources( "`find $HOME -name '*.A' -print`" ); 230 231 This example sources every file ending with `.A' found in any 232 subdirectory under your home directory. 233 234 235File: algae.info, Node: src, Next: strip, Prev: sources, Up: Execution 236 237 - Function: src ( filename ) 238 The `src' function finds and opens a file of Algae code, executes 239 the statements within it at global scope, and then closes the file. 240 This function, rather than `source' or `sources', is intended to 241 be the normal way to source files directly. Other functions that 242 may be used to source files are `require' and `autosrc'. 243 244 To find the file, `src' looks first for a file named `FILENAME.A', 245 that is, it appends `.A' to the name given by the argument 246 FILENAME. If a file with that name exists, it is sourced; 247 otherwise, `src' looks for a file named FILENAME with nothing 248 appended, and sources it if it exists. 249 250 If FILENAME is a relative file name, such as `foo' or `foo/bar.A', 251 `src' searches for the file using the variable `$src_path'. It 252 appends FILENAME to each of the directories listed in the 253 character vector `$src_path' (both with and without the `.A'), and 254 sources the first file it finds whose name matches. The current 255 default directory is tried only if it is specified in `$src_path'. 256 257 No directory searching is performed if FILENAME is an absolute 258 file name. File names that begin with `/', `./', `../', or `~/' 259 are absolute. If the file name begins with `~/', the tilde is 260 replaced with the value of the `HOME' environment variable. 261 262 A file name that begins with the `!' character is a pipe; the rest 263 of the file name is given as a command line to the shell, the 264 standard output of which is then read by `src'. For example, 265 266 src("!m4 foo.A") 267 268 runs the file `foo.A' through the `m4' macro preprocessor first 269 before `src' reads it. 270 271 The `$src_path' vector is initialized from the environment variable 272 `ALGAE_SRC_PATH', if it exists. It may be modified in either of 273 the startup files `/usr/local/lib/algae/4.3.6/algae.A' or 274 `$HOME/.algae'. (*Note Startup Files::.) 275 276 The syntax of `ALGAE_SRC_PATH' is the same as that of `PATH' for 277 the shell; fields are separated by `:', and `.' is used for the 278 current default directory. To set `ALGAE_SRC_PATH' in the Bourne 279 shell, type something like the following: 280 281 export ALGAE_SRC_PATH 282 ALGAE_SRC_PATH=.:~/algae:/usr/local/lib/algae 283 284 Execution of the Algae code in FILENAME begins at global scope. 285 For example, if the source file contains the single statement 286 `x=1', the assignment is made to the global variable X regardless 287 of whether `src' was called from within a function or not. 288 289 The `src' function raises an exception if FILENAME cannot be 290 found. It returns `NULL' if it cannot be opened, a negative integer 291 if a parse or run-time error occurs, and 0 otherwise. 292 293 294File: algae.info, Node: strip, Next: system, Prev: src, Up: Execution 295 296 - Function: strip ( f ) 297 The `strip' function removes all file and line information from the 298 given function F. The parser ordinarily includes this information 299 so that, for example, run-time error messages can identify the 300 line on which they occurred. If an error occurs in a function 301 that has been stripped, then the error is attributed instead to 302 the calling expression. 303 304 This function may also be useful in conjunction with profiling. 305 Any time spent in a call to a stripped function gets charged to 306 the file and line from which it was called. 307 308 All members of F are left unchanged as members of the return value. 309 310 311File: algae.info, Node: system, Prev: strip, Up: Execution 312 313 - Function: system ( s ) 314 This function passes the string S to the command processor for 315 execution. On a UNIX system, for example, the statement 316 `system("ls")' lists the files in the current directory. If the 317 call succeeds, the exit status is returned; otherwise a -1 is 318 returned. 319 320 321File: algae.info, Node: Special Tools, Next: Miscellaneous, Prev: Execution, Up: Standard Functions 322 323Special Tools 324============= 325 326* Menu: 327 328* npsol:: nonlinear optimization 329* plot:: plot curves 330* replot:: modify a plot 331* splot:: plot surfaces 332* umin:: unconstrained minimization 333* unplot:: terminate plots 334 335 336File: algae.info, Node: npsol, Next: plot, Prev: Special Tools, Up: Special Tools 337 338 - Function: npsol ( objective; start; constraints; options; state ) 339 The `npsol' function uses a sequential quadratic programming method 340 to minimize a given objective function subject to given 341 constraints. The domain of the objective function is called the 342 "design space", and the coordinates of the design space are called 343 "design variables". 344 345 This function uses the NPSOL package of Fortran routines developed 346 and sold by Stanford University. Your version of Algae might not 347 have the `npsol' builtin function; if not, it probably means that 348 you don't have a license for NPSOL or that there was some problem 349 installing it on your computer. 350 351 The `npsol' function may not be called recursively. 352 353 The OBJECTIVE argument may be either a function or a table. If a 354 function, then it's assumed to take one argument, a vector of 355 design variables, and return the value of the objective at that 356 point. If OBJECTIVE is a table, it may have the following members: 357 358 `objf' 359 A function that returns the value of the objective function 360 for the vector of design variables given as its first 361 argument. If the member `params' exists in OBJECTIVE, then 362 it is passed as a second argument to `objf'. 363 364 `objgrd' 365 A function that returns the sensitivities of the objective 366 function; that is, the first derivatives with respect to the 367 design variables. Its arguments are the same as for `objf'. 368 369 `params' 370 This member, if it exists, is passed as the second argument to 371 `objf' and `objgrd', providing a means for passing additional 372 parameters to those functions. 373 374 Only the `objf' member is required. If the objective derivatives 375 are not provided, you must ensure that `derivative_level' is set 376 accordingly. 377 378 The START argument is a vector that specifies the starting point. 379 380 The CONSTRAINTS argument is a table that may contain any of all of 381 the following members: 382 383 `side_constraints' 384 A matrix that specifies upper and lower constraints on values 385 of the design variables. This matrix has two columns, the 386 first column giving lower bounds and the second column giving 387 upper bounds. If this member is not given, then a default is 388 provided using 1.0E10 as "infinity". In that case, you 389 should be aware that NPSOL will take these values literally 390 if you also use the "infinite_bound" option (in OPTIONS) with 391 a value greater than 1.0E10. 392 393 `linear_constraints' 394 A table that may contain any or all of the following members: 395 396 `coefficients' 397 A matrix of the linear constraint coefficients. The 398 i-th row contains the coefficients for the i-th linear 399 constraint. 400 401 `bounds' 402 A matrix, like `side_constraints', that gives the upper 403 and lower bounds for the linear constraints. If not 404 given, defaults are provided as with `side_constraints'. 405 406 `nonlinear_constraints' 407 A table that may contain any or all of the following members: 408 409 `values' 410 Either a function that computes the vector of nonlinear 411 constraint function values at the given point, or a 412 table in which member `conf' is a function returning the 413 values and `congrd' is a function returning the 414 gradients. The constraint gradients, if provided, 415 should be given as a matrix in which the rows correspond 416 to the constraints and the columns correspond to the 417 design variables. As in OBJECTIVES, a member called 418 `params' may also be included. 419 420 `bounds' 421 A matrix, like `side_constraints', that gives the upper 422 and lower bounds for the nonlinear constraints. If not 423 given, defaults are provided as with `side_constraints'. 424 425 If the constraint derivatives are not provided, you must 426 ensure that `derivative_level' is set accordingly. 427 428 The OPTIONS argument is a table that may contain any of the 429 valid NPSOL options. For example, `{ hessian = "yes" }' 430 specifies the corresponding option in NPSOL. Use an 431 underscore instead of blanks between words, as in `{ 432 major_print_level = 1 }'. The valid options are: 433 434 `central_difference_interval' 435 If the algorithm switches to central differences because 436 the forward-difference approximation is not sufficiently 437 accurate, this value is used as the difference interval 438 for every variable. 439 440 `cold_start' 441 `warm_start' 442 These flags control the specification of the initial 443 working set in both the procedure for finding a feasible 444 point for the linear constraints and bounds, and in the 445 first QP subproblem thereafter. With a `cold_start', 446 the first working set is chosen by `npsol' based on the 447 values of the variables and constraints at the initial 448 point. Broadly speaking, the initial working set will 449 include equality constraints and bounds or inequality 450 constraints that violate or "nearly" satisfy their 451 bounds within `crash_tolerance'. With a `warm_start', 452 the user must provide the `state' table. A warm start 453 will be advantageous if a good estimate of the initial 454 working set is available--for example, when `npsol' is 455 called repeatedly to solve related problems. 456 457 `crash_tolerance' 458 This value is used in conjunction with the optional 459 parameter `cold_start', which is the default. When 460 making a cold start, the QP algorithm in `npsol' must 461 select an initial working set. The initial working set 462 will include, if possible, bounds or general inequality 463 constraints that lie within `crash_tolerance' of their 464 bounds. The default value is 0.01. If 465 `crash_tolerance' is less than zero or greater than one, 466 the default value is used. 467 468 `derivative_level' 469 This value indicates which objective and constraint 470 derivatives are provided by the user. The choices are 471 as follows: 472 473 `0' 474 Neither objective nor constraint derivatives are 475 provided. 476 477 `1' 478 The objective derivatives are provided by the 479 `objgrd' function in argument OBJECTIVE. 480 Constraint derivatives are not provided. 481 482 `2' 483 The nonlinear constraint derivatives are provided 484 by the `congrd' function in argument CONSTRAINTS. 485 Objective derivatives are not provided. 486 487 `3' 488 The objective derivatives are provided by the 489 `objgrd' function in argument OBJECTIVE, and the 490 nonlinear constraint derivatives are provided by 491 the `congrd' function in argument CONSTRAINTS. 492 493 The value 3 is the default, and should be used whenever 494 possible, since `npsol' is more reliable and will 495 usually be more efficient when all derivatives are exact. 496 497 If `derivative_level' is 0 or 2, `npsol' will estimate 498 the objective gradients using finite differences. The 499 computation of finite-difference approximations usually 500 increases the total run time, since a call to the 501 objective function is required for each constraint. 502 Furthermore, less accuracy can be attained in the 503 solution. 504 505 If `derivative_level' is 0 or 1, `npsol' will 506 approximate the constraint gradients. One call to the 507 constraint function is required for each variable. At 508 times, central differences are used rather than forward 509 differences, in which case twice as many calls to the 510 objective and constraint functions are needed. The 511 switch to central differences is not under the user's 512 control. 513 514 `difference_interval' 515 This value defines an interval used to estimate 516 gradients by finite differences in the following 517 circumstances: (1) for verifying the objective and 518 constraint gradients, and (2) for estimating the 519 objective or constraint derivatives. If a difference 520 interval is not specified by the user, a finite 521 difference interval will be computed automatically for 522 each variable by a procedure that requires up to six 523 calls of the objective and constraint functions for each 524 component. This option is recommended if the function 525 is badly scaled or the user wishes to have `npsol' 526 determine constant elements in the objective and 527 constraint gradients. 528 529 `feasibility_tolerance' 530 This value defines the maximum acceptable absolute 531 violations in linear and nonlinear constraints at a 532 "feasible" point; i.e., a constraint is considered 533 satisfied if its violation does not exceed this value. 534 The default value is the square root of machine 535 precision. 536 537 `function_precision' 538 This value is intended to be a measure of the accuracy 539 with which the objective and constraint functions can be 540 computed. It acts as a relative precision when the 541 magnitude is large, and as an absolute precision when 542 the magnitude is small. For example, if the objective 543 function is typically on the order of 1000 and the first 544 6 digits are known to be correct, then 545 `function_precision' should be set to 1.0E-6. In 546 contrast, if the objective function is typically on the 547 order of 1.0E-4 and the first 6 digits are known to be 548 correct, then `function_precision' should be set to 549 1.0E-10. The choice of `function_precision' can be 550 quite complicated for badly scaled problems. The 551 default value is machine precision raised to the 0.9 552 power; this is appropriate for most simple functions 553 that are computed with full accuracy. However, when the 554 accuracy of the computed function values is known to be 555 significantly worse than full precision, then 556 `function_precision' should be large enough that `npsol' 557 will not attempt to distinguish between function values 558 that differ by less than the error inherent in the 559 calculation. 560 561 `hessian' 562 This option must be either `"yes"' or `"no"'. (The 563 default is `"no"'). This option controls the contents 564 of the `R' matrix in STATE. The user should set 565 `hessian' to `"yes"' if the `state' table returned is to 566 be used for a subsequent warm start. 567 568 `infinite_bound_size' 569 If this value is greater than zero, it defines the 570 "infinite" bound in the definition of the problem 571 constraints. Any upper bound greater than or equal to 572 this value will be regarded as positive infinity. Any 573 lower bound less than or equal to the negative of this 574 value will be regarded as negative infinity. The 575 default value is 1.0E10. 576 577 `infinite_step_size' 578 This value specifies the magnitude of the change in 579 variables that is treated as a step to an unbounded 580 solution. If the change in any variable during an 581 iteration would exceed the value of 582 `infinite_step_size', the objective function is 583 considered to be unbounded below in the feasible region. 584 The default is the greater of `infinite_bound_size' and 585 1.0E10. 586 587 `iteration_limit' 588 This value specifies the maximum number of major 589 iterations allowed before termination. 590 591 `linear_feasibility_tolerance' 592 `nonlinear_feasibility_tolerance' 593 These values define the maximum acceptable absolute 594 violations in linear and nonlinear constraints at a 595 "feasible" point. A constraint is considered satisfied 596 if its violation does not exceed this value. The 597 default value for both options is the square root of 598 machine precision. 599 600 On entry to `npsol', an iterative procedure is executed 601 in order to find a point that satisfies the linear 602 constraints and bounds on the variables to within 603 `linear_feasibility_tolerance'. All subsequent iterates 604 will satisfy the linear constraints to within the same 605 tolerance, unless this value is comparable to the finite 606 difference interval. 607 608 For nonlinear constraints, 609 `nonlinear_feasibility_tolerance' defines the largest 610 constraint violation that is acceptable at an optimal 611 point. Since nonlinear constraints are generally not 612 satisfied until the final iterate, this value acts as a 613 partial termination criterion for the iterative sequence. 614 615 These tolerances should reflect the precision of the 616 corresponding constraints. for example, if the 617 variables and the coefficients in the linear constraints 618 are of order unity, and the latter are correct to about 619 6 decimal digits, it would be appropriate to specify 620 `linear_feasibility_tolerance' as 1.0E-6. 621 622 `linesearch_tolerance' 623 This value controls the accuracy with which a step taken 624 during each iteration approximates a minimum of the 625 merit function along the search direction. The smaller 626 the value, the more accurate the line search. The 627 default value is 0.9; it requests an inaccurate search 628 that is appropriate for most problems, particularly 629 those with any nonlinear constraints. 630 631 If there are non nonlinear constraints, a more accurate 632 search may be appropriate when it is desirable to reduce 633 the number of major iterations--for example, if the 634 objective function is cheap to evaluate or if the 635 gradients are not specified. 636 637 `list' 638 If this flag is given, all of the options and their 639 values are printed. 640 641 `print_level' 642 This value controls the amount of printed output 643 produced by the major iterations of `npsol'. The levels 644 are as follows: 645 646 `0' 647 No output. This is the default. 648 649 `1' 650 The final solution only. 651 652 `5' 653 One line of output for each major iteration, but no 654 final solution. 655 656 `10' 657 The final solution and one line of output for each 658 iteration. 659 660 `20' 661 At each major iteration, the objective function, 662 the Euclidean norm of the nonlinear constraint 663 violations, the value of the nonlinear constraints, 664 the values of the linear constraints, and the 665 current values of the variables. 666 667 `minor_iteration_limit' 668 This value specifies the maximum number of iterations 669 for the optimality phase of each QP subproblem. 670 671 `minor_print_level' 672 This value controls the amount of printout produced by 673 the minor iterations of `npsol'. The levels are as 674 follows: 675 676 `0' 677 No output. This is the default. 678 679 `1' 680 The final QP solution. 681 682 `5' 683 One line of output for each minor iteration, but no 684 final QP solution. 685 686 `10' 687 The final QP solution and one line of output for 688 each minor iteration. 689 690 `20' 691 At each minor iteration, the current estimates of 692 the QP multipliers, the current estimate of the QP 693 search direction, the QP constraint values, and the 694 status of each QP constraint. 695 696 `optimality_tolerance' 697 This value specifies the accuracy to which the user 698 wishes the final iterate to approximate a solution of 699 the problem. Broadly speaking, it indicates the number 700 of correct figures desired in the objective function at 701 the solution. For example, if `optimality_tolerance' is 702 1.0E-6 and `npsol' terminates successfully, the final 703 value of the objective function should have 704 approximately 6 correct figures. The `npsol' function 705 will terminate successfully if the iterative sequence is 706 judged to have converged and the final point satisfies 707 the first-order optimality conditions. 708 709 `verify_level' 710 This value refers to finite-difference checks on the 711 gradients computed by the user function `objgrd' and 712 `congrd'. It may take on one of the following values: 713 714 `-1' 715 No checks are made. 716 717 `0' 718 Perform only a very inexpensive check, involving 719 one call to the objective function and one call to 720 the constraint function. 721 722 `1' 723 Perform a reliable but expensive check on the 724 objective gradients. 725 726 `2' 727 Perform a reliable but expensive check on the 728 constraint gradients. 729 730 `3' 731 Perform reliable but expensive checks on both the 732 objective and the constraint gradients. 733 734 These checks are recommended whenever a new function 735 routine is being developed. 736 737 The STATE argument is used only when the NPSOL "warm_start" 738 option is requested. It may be obtained from the return of a 739 previous call to `npsol'. Its members are: 740 741 `ISTATE' 742 A vector describing the status of the constraints. 743 744 `CLAMDA' 745 The Lagrange multiplier estimates for the nonlinear 746 constraints. 747 748 `R' 749 The factored Hessian of the Lagrangian function. 750 751 The `npsol' function returns a table containing the following 752 members: 753 754 `objective' 755 The value of the objective function at the final iterate. 756 757 `solution' 758 The solution vector (or final estimate) for the problem. 759 760 `inform' 761 The INFORM value (success/error indicator) returned by 762 NPSOL. The possibilities are: 763 764 `0' 765 The iterates have converged to a point that 766 satisfies the first-order optimality conditions to 767 the accuracy requested by the optional parameter 768 `optimality_tolerance', i.e., the projected 769 gradient and active constraint residuals are 770 negligible. (Success.) 771 772 `1' 773 The final iterate satisfies the first-order 774 optimality conditions to the accuracy requested, 775 but the sequence of iterates has not yet converged. 776 NPSOL was terminated because no further improvement 777 could be made in the merit function. (Probable 778 success.) 779 780 `2' 781 No feasible point could be found for the linear 782 constraints and bounds. The problem has no 783 feasible solution. 784 785 `3' 786 No feasible point could be found for the nonlinear 787 constraints. The problem may have no feasible 788 solution. 789 790 `4' 791 The limiting number of iterations, determined by 792 the optional parameter `major_iteration_limit', has 793 been reached. 794 795 `6' 796 The current point does not satisfy the first-order 797 optimality conditions, and no improved point for 798 the merit function could be found during the final 799 line search. 800 801 `7' 802 The user-provided derivatives of the objective 803 function and/or nonlinear constraints appear to be 804 incorrect. 805 806 `9' 807 An input parameter is invalid. 808 809 `iter' 810 The number of major iterations performed. 811 812 `state' 813 The `state' table described above. 814 815 816File: algae.info, Node: plot, Next: replot, Prev: npsol, Up: Special Tools 817 818 - Function: plot ( ... ) 819 The `plot', `splot', `replot', and `unplot' functions provide an 820 interface to the gnuplot program for plotting data. Use `plot' 821 for plotting lines in two or three dimensions; `splot' is for 822 plotting surfaces in three dimensions. 823 824 To use these plotting functions effectively, you will probably 825 need some familiarity with the gnuplot commands. For example, to 826 add a title to an existing plot, you'd type something like 827 `replot("set title 'Good Stuff'")'. Read the gnuplot manual or 828 its on-line help for more information. 829 830 The `plot' function accepts as many as three arguments. If either 831 or both of the first two arguments are (or can be converted to) 832 character vectors, then their elements are sent, each on a separate 833 line, to gnuplot as commands. For example, `plot("set term X11")' 834 causes gnuplot to generate X11 output. Even commands that request 835 information from gnuplot, like `plot("show term")' are acceptable 836 (although you might temporarily lose sight of Algae's prompt). 837 Don't use the "exit" or "quit" commands of gnuplot--they cause 838 gnuplot to exit without Algae knowing about it. 839 840 If more than one argument is given to `plot' and the last one is an 841 integer scalar, then it is taken to be an identifier for the plot 842 process. This allows you to have more than one plot open at a 843 time. If no identifier is given, then the active plot is killed 844 and replaced by a new one with the same identifier. The "active" 845 plot is the one last referenced, or 1 if there are no plots open. 846 The `replot' function may be used to modify an open plot. 847 848 Any other arguments given to `plot' are taken to be data to be 849 plotted. Vectors are plotted using their element values as 850 ordinates and their labels for the abscissae. Matrices with 2 851 columns are plotted using the second column for ordinates and the 852 first column for abscissae. A matrix with 3 columns is plotted as 853 a curve in three dimensions, with the third column specifying the 854 ordinates. Surface plots are obtained using the `splot' function. 855 856 If the data given to `plot' is a vector, but has no labels, then 857 the element indices are used instead of the labels. 858 859 Multiple curves may be shown on the same plot, either by giving 860 `plot' two data arguments or (better yet) supplying the data in a 861 table. When data is given in a table (even if it contains only one 862 member), the member name is used in the plot legend. Otherwise, 863 `plot' uses the names "y_1" and "y_2". 864 865 If the data is given in a table, any members that are tables 866 themselves are given to gnuplot in a single data file. This means 867 that the same line and point type is used. For example, if `x' 868 and `y' are vectors to be plotted, then `plot({x;y})' plots the 869 two, each with a different line and point type and described by 870 name in the legend. On the other hand, `plot({z={x;y}})' plots 871 them with the same line and point type and names the combination 872 "z" in the legend. 873 874 If `plot' is called with no arguments, it returns a vector of the 875 open plot identifiers. This vector is sorted from most to least 876 recently referenced, so the "active" plot is first. 877 878 Here's an example that simulates the Van der Pol system and plots 879 the results: 880 881 xdot = function( t; x ) { 882 return x[1]*(1-x[2]^2)-x[2], x[1]; 883 } 884 x = ode4( xdot; 0; 20; 0,.25 ); 885 plot( "set data style lines"; { x1=x[1;]; x2=x[2;] } ); 886 887 See also `splot', `replot', and `unplot'. 888 889 890File: algae.info, Node: replot, Next: splot, Prev: plot, Up: Special Tools 891 892 - Function: replot ( ... ) 893 The `replot' function is used to modify or redisplay plots created 894 with either the `plot' or `splot' functions. It takes at most 2 895 arguments. If the first argument has character type, it is passed 896 to gnuplot as commands. 897 898 The last argument is the optional plot identifier. If not given, 899 the active plot is used by default. 900 901 See also `plot', `splot', and `unplot'. 902 903 904File: algae.info, Node: splot, Next: umin, Prev: replot, Up: Special Tools 905 906 - Function: splot ( ... ) 907 The `splot' function is used to plot surfaces in three dimensions. 908 Except for the form of the data, its input is identical to that of 909 the `plot' function. The data is specifed as a matrix of 910 ordinates. The labels of the matrix, or the corresponding indices 911 if the labels don't exist, are used for the abscissae. 912 913 See also `plot', `replot', and `unplot'. 914 915 916File: algae.info, Node: umin, Next: unplot, Prev: splot, Up: Special Tools 917 918 - Function: umin ( objective; start; options ) 919 The `umin' function performs unconstrained minimization using the 920 Nelder-Mead direct search method. It does not have the features or 921 sophistication of `npsol', but it works well for some 922 cases--particularly when the objective surface is not smooth. 923 924 The OBJECTIVE argument is a function that takes one or two 925 arguments and returns the value of the objective at that point. 926 The first argument is a vector of design variables. The second 927 argument, which is optional, is passed unchanged from the PARAMS 928 member of the OPTIONS argument to `umin' itself. 929 930 The START argument is an integer or real vector that specifies the 931 starting point. 932 933 The OPTIONS augument may be either NULL or a table containing 934 convergence and other specifications. The meaningful options are: 935 936 `bound' 937 The minimum value permitted for the objective function. The 938 default is -1e32. 939 940 `display' 941 A function called at each "successful" iteration with the 942 current design point as its only argument. This may be used, 943 for example, to plot the design as it changes. 944 945 `evals' 946 The maximum number of objective function evaluations 947 permitted. The default value is 1000. 948 949 `iter' 950 The maximum number of iterations permitted. The default 951 value is 100. 952 953 `params' 954 The value of this member is passed as the second argument to 955 the objective function. 956 957 `right' 958 If this member exists, then the initial simplex has right 959 angles. By default, the initial simplex has sides of equal 960 length. 961 962 `size' 963 The initial size of the simplex. By default, this is the 964 greater of 1 and the infinity norm of the starting vector. 965 966 `tol' 967 The relative size of the simplex, below which the iteration 968 is taken to have converged. The tolerance is 1e-6 by default. 969 970 `verbose' 971 If this member exists, then information is printed at each 972 "successful" iteration. 973 974 The return value from `umin' is a table with the following members: 975 976 `evals' 977 The number of objective function evaluations. 978 979 `inform' 980 A return code specifying success or failure: 981 982 `0' 983 success 984 985 `1' 986 failure, objective bound reached 987 988 `2' 989 failure, function evaluation limit exceeded 990 991 `3' 992 failure, iteration limit exceeded 993 994 `iter' 995 The number of iterations performed. 996 997 `msg' 998 A message corresponding to the inform code. 999 1000 `obj' 1001 The final objective value. 1002 1003 `sol' 1004 The final design point. 1005 1006 This code is based on `nmsmax', a MATLAB function by Nick Higham. 1007 1008 See also `npsol'. 1009 1010 1011File: algae.info, Node: unplot, Prev: umin, Up: Special Tools 1012 1013 - Function: unplot ( id ) 1014 The `unplot' function is used to terminate plots created with the 1015 `plot' or `splot' functions. The integer scalar or vector 1016 argument ID specifies the identifiers of the plots to be 1017 terminated. If no ID is given, the active plot is terminated. 1018 You can terminate all open plots with `unplot(plot())'. 1019 1020 See also `plot', `replot', and `splot'. 1021 1022 1023File: algae.info, Node: Miscellaneous, Prev: Special Tools, Up: Standard Functions 1024 1025Miscellaneous 1026============= 1027 1028* Menu: 1029 1030* all:: test all elements 1031* atof:: convert string to number 1032* char:: vector to character string 1033* class:: entity class 1034* equal:: test for equality 1035* members:: members of a table 1036* info:: documentation browsing system 1037* prof:: summarize profiler output 1038* show:: show entity information 1039* split:: split string into fields 1040* string:: convert to character type 1041* substr:: return a substring 1042* test:: truth test 1043* time:: user time 1044* tolower:: convert strings to lower case 1045* toupper:: convert strings to upper case 1046* what:: list functions 1047* who:: list variables 1048 1049 1050File: algae.info, Node: all, Next: atof, Prev: Miscellaneous, Up: Miscellaneous 1051 1052 - Function: all ( x ) 1053 The `all' function evaluates the "truth" of its argument X in the 1054 same way that the function `test' does, except that vectors and 1055 matrices are "true" only if all of their elements are "true". For 1056 example, `all(1,0)' returns 0 while `test(1,0)' returns 1. If X 1057 has no elements, `all' returns 0. 1058 1059 See also `test' and `equal'. 1060 1061 1062File: algae.info, Node: atof, Next: char, Prev: all, Up: Miscellaneous 1063 1064 - Function: atof ( s ) 1065 The `atof' function converts character strings to real numbers. 1066 The argument S may be a scalar, vector, or matrix. The function 1067 reads only up to the first unrecognized character of each string, 1068 and ignores anything that remains. If the first character of a 1069 string is unrecognized, then the value is taken to be zero. 1070 1071 1072File: algae.info, Node: char, Next: class, Prev: atof, Up: Miscellaneous 1073 1074 - Function: char ( v ) 1075 The `char' function converts the vector V into a character string; 1076 each element of V contributes a single character according to its 1077 ASCII value. For example, `char(65,66,67)' returns the string 1078 `"ABC"'. 1079 1080 If an element of V is less than 0 or greater than 255, then it 1081 will "wrap" (modulo 256). Thus `char(65)' and `char(65+256)' both 1082 return the string `"A"'. 1083 1084 Algae's character strings are terminated with a NUL (0) character. 1085 For the `char' function, that means that if an element of V is 1086 zero (or a multiple of 256) then the string is terminated at that 1087 point. For example, `char(65,0,66)' yields the string `"A"'. 1088 1089 1090File: algae.info, Node: class, Next: equal, Prev: char, Up: Miscellaneous 1091 1092 - Function: class ( x ) 1093 The `class' function returns a character string (such as "scalar" 1094 or "table") that describes the class of X. 1095 1096 1097File: algae.info, Node: equal, Next: members, Prev: class, Up: Miscellaneous 1098 1099 - Function: equal ( a; b ) 1100 This function tests A and B for equality. For vectors and 1101 matrices, it returns true (1) only if every pair of corresponding 1102 elements is equal, and false (0) otherwise. For all other 1103 classes, this function returns the same value as the expression 1104 `a==b' would. 1105 1106 See also `test'. 1107 1108 1109File: algae.info, Node: members, Next: info, Prev: equal, Up: Miscellaneous 1110 1111 - Function: members ( e ) 1112 This function returns a vector containing the names of the members 1113 of E. 1114 1115 1116File: algae.info, Node: info, Next: prof, Prev: members, Up: Miscellaneous 1117 1118 - Function: info ( topic ) 1119 This function starts up an interactive browser for Algae's 1120 documentation. The optional argument TOPIC (a character scalar) 1121 takes you directly to that topic. For example, `info("sort")' 1122 takes you directly to the description of the `sort' function. 1123 1124 If possible, `info' uses an X-based html browser (like netscape or 1125 mosaic). Otherwise, a character-based html browser (like lynx) 1126 will be tried. As a final resort, the GNU Info browser is called. 1127 1128 The names of the available browsers are assigned by the startup 1129 code (*note Startup Files::) as members `xhtml', `html', and 1130 `info' of the global table `$programs'. To prevent Algae from 1131 using a particular browser, simply set the appropriate member of 1132 `$programs' to a zero-length string. If you prefer to use Info, 1133 for example, you could simply put the line 1134 1135 $programs.xhtml = $programs.html = ""; 1136 1137 in your `.algae' file. 1138 1139