Home

Merlin user`s manual

Contents

1. f x 4h dz 45 2h 45 4h 45 8h ANAL The user written code SUBROUTINE GRANAL is used to calculate the derivatives 6 5 2 MIXED Syntax classification RAVAC Purpose Allows different modes to be assigned to specified gradient components Examples To calculate the first 3 components in ANAL mode the fourth in NUMER etc use MIXED 1 3 ANAL 4 NUMER 5 FAST 6 QUAD or abbreviating MIXED 1 3 A4N5 F 6 Q in an obvious correspondence 6 5 3 JNUMER JANAL Syntax classification SIC Purpose Make a choice for the manner the Jacobian is calculated JNUMER selects numerical estimation using forward differences JANAL selects the user supplied code SUBROUTINE JANAL 6 5 4 HESSIAN Syntax classification PAC Purpose Calculates and manipulates the Hessian matrix The associated panel is listed in figure 6 13 The panel parameters are as follows DO Determines the action of the command Allowed values are eC Calculate the Hessian matrix e D Decompose an already calculated Hessian matrix to its Choleski factors e M Compose the Hessian matrix from its Choleski factors Modes of operation and related commands 65 Keyword Description Allowed values Desired Action 1c d m p r w Function Gradient Anal f g a MODE1 Function Gradient Anal f g a MODE2 Function Gradient Anal f g a FILE File to write to HESSIAN Any string CANCEL Cancel Proceed 1 0 1 Figure 6 13 The HESSIAN panel e P Compare two method
2. Arguments e NARGS output The number of arguments in the current MERLIN command This number does not include the command name itself 9 4 3 SUBROUTINE GETARG Definition SUBROUTINE GETARG NA ARG LENARG INTEGER NA LENARG CHARACTER ARG Purpose Returns an argument from the MERLIN command line Arguments e NA input Index of the argument to be returned with 0 lt NA lt NARGS NARGS can be obtained with a call to SUBROUTINE ARGNO When NA O the command name itself is returned Miscellaneous glue routines 133 e ARG output The NA argument from the MERLIN command line It must have adequate length to accommodate all possible arguments e LENARG output Effective length of ARG 9 4 4 SUBROUTINE GETACC Definition SUBROUTINE GETACC ACC REAL ACC Purpose Returns the relative machine accuracy as estimated by MERLIN or as set by the MACHINE_DIGITS directive in the configuration file Arguments e ACC output The relative machine accuracy It is the largest positive number for which under the machine s finite precision the following conditions hold 1 acc 1 1 acc 1 9 4 5 SUBROUTINE GETMC Definition SUBROUTINE GETMC BIG SMALL REAL BIG SMALL Purpose Returns some machine constants These should be set in the MERLIN configuration file as they are system and installation dependent Arguments e BIG output The largest floating point number this machine can handle e SMALL output
3. Figure 6 8 The TRUST panel e 1 The specified accuracy has been satisfied e 2 Further progress is impossible due to rounding errors e 3 Further progress is impossible e 4 Some input parameters are incorrect e 5 Inconsistent equality constraints e 6 Inconsistent constrains bounds e 7 All of the constrains cannot be satisfied e 8 All function evaluations have been used e 9 Target value has been reached 6 3 6 TRUST Syntax classification PAC Purpose Invokes the BFGS minimization algorithm using a trust region method and Choleski decomposition for the Hessian The associated panel is listed in figure 6 8 The panel parameters are as follows NOC An approximate upper bound for the number of calls to the objective function PRINT Determines the amount of output from the minimization method Allowed values are e 0 No printout at all e 1 Display lower function values as they are discovered 54 GTOL XTOL FTOL ITER MAD USEG USEH USER RHO CANCEL Command description e 2 Display function and parameter values as well The gradient termination criterion The method terminates when the relative gradient falls below GTOL Termination criterion based on the values of the parameters The method terminates when the relative change in the parameters in two successive iterations is less than XTOL Termination criterion based on function values The method terminates when the rela tive
4. e 0 No printout at all e 1 Display lower function values as they are discovered e 2 Display function and parameter values as well Specifies the termination accuracy Specifies whether the MERLIN Automatic Derivatives are to be used when approximating the gradient vector Allowed values are e ON The MERLIN Automatic Derivatives are to be used e OFF Use the current derivative mode This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS GCALLS INFO Number of function evaluations that were performed Number of evaluations of the gradient vector Result code Possible values are Minimization related commands 53 Keyword Description Allowed values NOC Number of calls Any int gt 1 PRINT Printout level 0 1 2 GTOL G convergence criterion 0 lt real lt 1 XTOL X convergence criterion 0 lt real lt 1 FTOL F convergence criterion 0 lt real lt 1 ITER Iterations 1 Inf Any int gt 1 MAD Automatic derivatives On 0ff USEG Use Recalculate gradient 1 0 USEH Use Recalculate Hessian 1 0 USER Use Recalculate radius 1 0 RHO The rho line parameter 0 lt real lt 1 CANCEL Cancel Proceed 0 1
5. e WEAK The weak Wolfe Powell conditions are used The maximum number of iterations that are allowed in the line search The p parameter that defines an acceptable drop in function value The o parameter used in the termination criteria for the line search This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS GCALLS ITERDONE INFO Number of function evaluations that were performed Number of evaluations of the gradient vector Number of BFGS iterations that were performed Result code Possible values are e 1 Target value has been reached Minimization related commands Keyword NOC PRINT GTOL XTOL FTOL ITER MAD USEG USEH LS LSITER RHO SIGMA CANCEL Description Number of calls Printout level G convergence criterion X convergence criterion F convergence criterion Iterations 1 Inf Automatic derivatives Use Recalculate gradient Use Recalculate Hessian Line search conditions Max LS iterations Line search rho Line search sigma Cancel Proceed Figure 6 6 The DFP panel e 2 The gradient criterion is satisfied e 3 All function evaluations have been used e 4 The X convergence criterion is satisfied
6. e5 The function value has converged e6 The Hessian matrix cannot be updated e 7 The specified number of iterations has been reached e 8 All variables are fixed e 9 Further progress is not possible 6 3 4 DFP Syntax classification PAC 51 Allowed values Any int gt 1 0 1 2 0 lt real lt 1 0 lt real lt 1 0 lt real lt 1 Any int gt 1 On 0ff 1 0 1 0 Strong Weak Any int gt 0 lt real 0 lt real 0 1 Purpose Invokes the DFP minimization algorithm using line search and Choleski decomposition for the Hessian The associated panel is listed in 6 6 The panel parameters are the same as for the BFGS command 6 3 5 TOLMIN Syntax classification PAC 52 Command description Ind Keyword Description Allowed values 1 NOC Number of calls Any int gt 1 2 PRINT Printout level 0 1 2 3 ACC Termination accuracy 0 lt real lt 1 4 MAD Automatic derivatives On Off 5 CANCEL Cancel Proceed 0 1 Figure 6 7 The TOLMIN panel Purpose Invokes the BFGS minimization algorithm using line search and the Goldfarb Idnani Z BZ I decomposition for the Hessian The associated panel is listed in figure 6 7 The panel parameters are as follows NOC PRINT ACC MAD CANCEL An approximate upper bound for the number of calls to the objective function Determines the amount of output from the minimization method Allowed values are
7. Definition INTEGER FUNCTION ISCOMP STR1 STR2 CHARACTER STR1 STR2 Purpose Performs a case insensitive comparison of the two character strings STR1 and STR2 Returns 0 if they don t match non zero if they match Arguments e STR1 input First string to be compared e STR2 input Second string to be compared 9 3 6 FUNCTION LENGTH Definition INTEGER FUNCTION LENGTH STR CHARACTER STR Purpose Returns the effective length of a character variable The effective length is defined as the position of the last non blank non tab character in the string Note that this is not the same as the declared length of a character variable Arguments e STR input A character variable of arbitrary length 132 MERLIN glue routines 9 4 Miscellaneous glue routines 9 4 1 SUBROUTINE GETDIM Definition SUBROUTINE GETDIM NOVAR NOTERM INTEGER NOVAR NOTERM Purpose Returns the number of parameters dimensionality of the objective function and the number of terms if the function is a sum of squared terms These numbers are provided by the user at the time SUBROUTINE MERLIN is called Arguments e NOVAR output Number of parameters of the objective function e NOTERM output Number of terms if the function is a sum of squares Otherwise NOTERM is set to 0 9 4 2 SUBROUTINE ARGNO Definition SUBROUTINE ARGNO NARGS INTEGER NARGS Purpose Returns the number of arguments in the current MERLIN command
8. Minimization commands 25 4 5 Minimization commands The minimization algorithms are invoked using the commands BFGS DFP TRUST TOLMIN CONGRA ROLL SIMPLEX LEVE and AUTO They all use the panel mechanism to obtain their input parameters and set the termination criteria All minimization commands use a few keywords with the same meaning NOC is an approximate upper bound to the allowed number of evaluations of the objective function PRINT controls the amount of output by the minimization algorithm Allowed values are e 0 suppresses all output e 1 reports each lower function value as it is discovered e 2 reports the function value as well as the values of the minimization parameters CANCEL controls whether execution of the minimization algorithm will proceed Allowed values are e 0 causes the user changes to be recorded in the panel the minimization algorithm will not be executed however e causes minimization to proceed normally Upon termination all minimization commands report the number of function and gradient calls that were performed as well as the number of iterations of the method MERLIN can estimate derivatives of the objective function using finite differences Three ways are implemented and correspond to the following modes of operation listed in order of increasing accu racy and computational cost FAST QUAD NUMER The minimization methods that use derivatives have the so called MAD option in th
9. The user must always construct one of the FUNCTION FUNMIN or the SUBROUTINE SUBSUM subpro grams However a dummy routine must be provided for the one that is left out since many linkers will not create the executable file otherwise We list below examples for the dummy subprograms FUNCTION FUNMIN X N DIMENSION X N END SUBROUTINE SUBSUM M N X F DIMENSION X N F M END The same action must be taken when the user does not wish to code the SUBROUTINE GRANAL the SUBROUTINE JANAL and the SUBROUTINE HANAL subprograms The dummy routines should read as SUBROUTINE GRANAL N X GRAD DIMENSION X N GRAD N END SUBROUTINE JANAL M N X FJ LD DIMENSION X N FJ LD N 18 END SUBROUTINE HANAL H LD N X DIMENSION H LD N X N END User written programs Chapter 4 The MERLIN Operating System MERLIN provides an operating system in order to render the optimization process efficient flexible and programmable MERLIN has a command interpreter as a front end that accepts the input commands and instructs the MERLIN s kernel to take appropriate action Like most operating systems the MERLIN Operating System MOS supports argumentary command packages called macros as well as command aliasing In addition there is the Merlin Control Language MCL through which one can device intelligent minimization strategies The MCL compiler is a separate software package built specifically for this purpose
10. M N X F DIMENSION X N F M M input is the number of the squared terms N input is the dimensionality of the problem X input is an array holding the values of the parameters zi F output is an array holding the values of the terms f x An example is given in figure 3 3 again for the Rosenbrock function with f 10 z gt z and fe 1 T2 The gradient vector 15 SUBROUTINE SUBSUM M N X F DIMENSION X N F M X1 X 1 X2 X 2 F 1 10 X2 X1 2 F 2 1 X1 END Figure 3 3 A sample SUBROUTINE SUBSUM SUBROUTINE GRANAL N X GRAD DIMENSION X N GRAD N X1 X 1 X2 X 2 T X2 X1 2 GRAD 1 400 X1 T 2 1 X1 GRAD 2 200 T END Figure 3 4 A sample SUBROUTINE GRANAL 3 4 The gradient vector This must be written as a subroutine subprogram SUBROUTINE GRANAL N X GRAD DIMENSION X N GRAD N N input is the dimensionality of the problem X input is an array holding the values of the parameters zi GRAD output is an array holding the values of the gradient components 2L An example for the Rosenbrock function is given in figure 3 4 Note that in earlier versions of MERLIN this routine had a different calling sequence 3 5 The Jacobian matrix This must be written as a subroutine subprogram 16 User written programs SUBROUTINE JANAL M N X FJ LD DIMENSION X N FJ LD N X1 X 1 X2 X 2 FJ 1 1 FJ 1 2 FJ 2 1 FJ 2 2
11. The smallest positive non zero floating point number this machine can handle 9 4 6 SUBROUTINE GETCNT Definition SUBROUTINE GETCNT NF NFP NG NGP NH NHP NJ NJP INTEGER NF NFP NG NGP NH NHP NJ NJP Purpose Returns the total and partial MERLIN counters All MERLIN counters are initialized to zero when MERLIN starts and are incremented when one of the user supplied subpro grams is called In addition the partial MERLIN counters are reset to zero each time a RESET command is issued There is no way to set the counters via a glue routine 134 Arguments MERLIN glue routines NF output Total number of evaluations of the objective function since MERLIN started calls to the user supplied FUNCTION FUNMIN NFP output Number of evaluations of the objective function since the last RESET command was issued NG output Total number of gradient evaluations calls to the user supplied SUBROUTINE GRANAL NGP output Number of gradient evaluations since the last RESET command was issued NH output Total number of Hessian evaluations calls to the user supplied SUBROUTINE HANAL NHP output Number of Hessian evaluations since the last RESET command was issued NJ output Total number of Jacobian evaluations calls to the user supplied SUBROUTINE JANAL NJP output Number of Jacobian evaluations since the last RESET command was issued 9 4 7 SUBROUTINE GETFLA Definition Purpose Arguments SUBROU
12. or m 2000 1 Any text editor can be used to construct and modify a macro MERLIN provides a simple facility to aid the construction of a macro Command MACRO initiates an interactive process that prompts for the macro name and its contents and finally stores the macro in the specially formatted multi macro file MACROF 28 The MERLIN Operating System Macros can conveniently automate certain procedures They are of limited use however since they don t provide mechanisms for conditional execution of commands or transfer of control One should use the MERLIN Control Language to implement complex tasks 4 7 Confidence intervals One of the most common uses of MERLIN is to fit a set of M data points ti yi to a model function y t x that depends on the N unknown parameters z Each measurement y has its own uncertainty e Assuming the measurement errors e are normally distributed around the true model y t the most likely set of parameters z is determined by minimizing the chisquare function fa gt Hawt 4 1 i l i The user is responsible for coding the objective function f as described in chapter 3 and invoke the MERLIN minimizers After a minimum has been found MERLIN is able to compute confidence intervals based on the covariance matrix of the fit the so called parabolic errors This approach assumes that either the model y t zm is linear in its parameters or the sample size M is large enough so that the unc
13. 6 18 6 19 6 20 6 21 6 22 6 23 6 24 6 25 6 26 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 List of Figures The BACKUP panel sorp a ga ds y ett NO s Ae ela eo oe a eS 69 Whe MEMO panels 2 onto a eG eel ae es tc ae 73 The DUMP panel n Secon ei we Ge eS Ee baw et ed 9 b QS OE W ales GS 74 Fhe INSPECT pael cia peek Ge e ee oe sh HOP Reece kee SE Si QG ks 76 The GRAPH panels ss yy aye ee BE Oe See 3 Z Se PE LE OG Cal Ee ee as 78 The PSGRAPH patiel 303 62a sc A a Acad ae at ee Gee 79 The COVARIANCE panel e 83 Output from the LIST command 85 Sample output from the HELP command 080224 85 Requesting help on panel keywords o 2 a s r s s r er ee ee ee 86 The CONTROL panel eis oe Boe Boke Soe WE Fee a Pee Eee E EAN 87 The HISTORY panel 228 0 ea koh a eae Pe AS pub ee Pa eas es 89 Sample plug in module an alternative to SHORTDIS 92 Output from the sample plug in module NEWSH 92 The structure of the MERLIN help file o o 94 Help text for the sample plug in module NEWSH 2 0 94 Sample plug in module that takes advantage of command line arguments 95 Sample plug in module that exploits the panel mechanism 97 Part of the panel description file corresponding to the PEXA sample plug in module 98 The panel of the PEXA sample plug in module as presented by MERLIN 98 Chapt
14. END Figure 3 5 A sample SUBROUTINE JANAL SUBROUTINE JANAL M N X FJ LD DIMENSION X N FJ LD N M input is the number of the squared terms N input is the dimensionality of the problem X input is an array holding the values of the variables z FJ output is an array holding the values FJ I J se LD input is the leading dimension of the matrix FJ used by MERLIN to store the Jacobian An example for the Jacobian of the Rosenbrock test function is shown in figure 3 5 3 6 The Hessian matrix This must be written as a subroutine subprogram SUBROUTINE HANAL H LD N X DIMENSION H LD N X N H output is an array holding the values of the Hessian elements G z LD input is the leading dimension of the matrix H used by MERLIN to store the Hessian N input is the dimensionality of the problem X input is an array holding the values of the parameters z Important note 17 SUBROUTINE HANAL H LD N X C Note We only have to fill the lower triangular including the C diagonal part of matrix H DIMENSION H LD N X N X1 X 1 X2 X 2 H 1 1 1200 X1 2 400 X2 2 H 2 1 400 X1 H 2 2 200 END Figure 3 6 A sample SUBROUTINE HANAL Note that only the lower triangular part of H must be filled in The rest of the Hessian matrix is completed by MERLIN using symmetry An example for the Hessian of the Rosenbrock function is shown in figure 3 6 3 7 Important note
15. Examples PROLOG prolog command Specifies that prolg command is a command to be executed after the configuration file has been read however before the first MERLIN prompt is displayed prolog command is any valid MERLIN command macro or MCL program invocation Additional arguments to the prolog command are allowed as if it were issued interactively As always the use of single quotes is mandatory if spaces are to be embedded Note that only one prolog command can be defined If PROLOG is used more than once the last one takes effect None If this directive is omitted no prolog is executed MERLIN only PROLOG point 1 5 PROLOG prl gt prl out PROLOG an_mcl_prog PROLOG ini 112 The MERLIN MCL configuration file 8 4 3 EPILOG Syntax EPILOG epilog command Purpose Specifies that epilog command is a command to be executed before MERLIN relinquishes control and either returns to the calling program as a result of a RETURN or QUIT command or stops as a result of a STOP command epilog command is any valid MERLIN command macro or MCL program invocation Additional arguments to the epilog command are allowed as if it were issued interactively As always the use of single quotes is mandatory if spaces are to be embedded Note that only one prolog command can be defined After MERLIN starts the epilog command can be changed using the EPILOG command Default None If this directive is omitted no prolog is executed
16. If a single question mark is entered at the panel s prompt information for all the parameters is issued 6 15 Odds and ends 6 15 1 ECHO Syntax classification UNC Syntax ECHO any_message Purpose Displays its arguments It can be used inside macros to issue informative messages Odds and ends 87 Ind Keyword Description Allowed values 1 DISKMAC Macros on regular files 0 1 2 ECHOMAC Macro start end messages 0 1 3 ECHOPRO Prolog epilog messages 0 1 4 MCLKEYS List MCL keywords 0 1 5 ECHOCOM Echo commands 0 1 6 KEEPIN Keep input file 0 1 7 KEEPOUT Keep output file 0 1 8 MCLBUF Use buffered MCL 0 1 Figure 6 25 The CONTROL panel Examples ECHO Minimization starts now ECHO A very long message 6 15 2 EPILOG Syntax classification UNC Syntax EPILOG epilog command Purpose Defines a command to be executed after a STOP RETURN or QUIT is issued by the user A blank argument ie EPILOG clears the epilog command The current epilog can be displayed using MODEDIS 6 15 3 CONTROL Syntax classification PAC Purpose Sets the parameters that control some MERLIN features The associated panel is listed in figure 6 25 The panel parameters are as follows DISKMAC Determines whether MERLIN should check in plain disk files for macros not present in the macro file MACROF For example if the macro abc is not present in the macro file MERLIN would check for the existenc
17. Purpose Arguments SUBROUTINE GETPPR PANEL KEY RVAL CHARACTER PANEL KEY REAL RVAL Subroutine GETPPR returns the floating point value RVAL assigned to the keyword KEY in the panel specified by PANEL e PANEL input The panel to be searched It must be a valid panel defined in the panel descrip tion file e KEY input The keyword to search for It must exist in the panel and have a real type otherwise this routine will abort e RVAL output The real value that corresponds to the keyword 9 2 6 SUBROUTINE GETPPS Definition Purpose Arguments SUBROUTINE GETPPS PANEL KEY SVAL LES CHARACTER PANEL KEY SVAL INTEGER LES Subroutine GETPPS returns the character string SVAL assigned to the keyword KEY in the panel specified by PANEL e PANEL input The panel to be searched It must be a valid panel defined in the panel descrip tion file e KEY input The keyword to search for It must exist in the panel and have a string or character type otherwise this routine will abort Panel related glue routines 125 e SVAL output The string or character value that corresponds to the keyword e LES output The effective length of SVAL 9 2 7 SUBROUTINE SETPI Definition SUBROUTINE SETPI KEY IVAL IERR CHARACTER KEY INTEGER IVAL IERR Purpose Subroutine SETPI assigns the integer number IVAL to the keyword KEY in the current panel Arguments e KEY input The keyword to
18. This chapter presents the most important MERLIN features A detailed description of all MERLIN commands is given in chapter 6 4 1 Commands MOS offers a repertoire of commands These can be classified into categories according to their action In order to present the general idea we will mention the most essential categories e Commands that manipulate the attributes of the minimization parameters The th mini mization parameter has the following attributes Its current value zi A unique symbolic name up to 10 characters long that may be set by the user An indication whether this parameter is fixed This is referred to as the fix status of the parameter The minimization routines do not alter the value of fixed parameters An indication whether there exist lower and or upper bounds for this parameter This is referred to as the margin status of the parameter The minimization routines make sure they never evaluate the function outside the allowed bounds 19 20 The MERLIN Operating System The lower bound if it exists The upper bound u if it exists e Commands that invoke one of the coded minimization algorithms e Commands that set the options for the various operation modes These modes determine the overall behavior of MERLIN For example there is the printout mode that determines the amount of output issued by MERLIN the gradient mode that determines the manner in which the gradient
19. Used by MERLIN only Examples EPILOG shortdis EPILOG dump what x file results 8 4 4 PLUG Syntax PLUG n plug_name Purpose Defines the names for user written plug in modules More specifically it defines that plug name should be used to reference the nth plug in This directive should be used when the user has programmed SUBROUTINE PLUGn Note that plug_name should not coincide with any of the MERLIN commands In case one wants to reference the plug in from an MCL program the plug name should not coincide with any of the McL statements Including non executable statements such as PROGRAM LOOP VAR etc Default None If this directive is omitted no plug in modules can be referenced even if the are embedded in the source code Used by MERLIN and MCL Examples PLUG 1 newsh PLUG 7 supermin 8 4 5 BIGGER Syntax BIGGER 3 Miscellaneous directives 113 Purpose Default Used by Examples Specifies that 6 is approximately the largest floating point number your machine can handle Note that according to installation 6 refers to either real or double precision arithmetic If this directive is omitted 8 defaults to 10 which is suitable for most computers in single precision MERLIN only BIGGER 1 E 300 8 4 6 SMALLER Syntax Purpose Default Used by Examples SMALLER c Specifies that o is approximately the smallest positive floating point number distin guishable from zero Note
20. e 15 3 4 A sample SUBROUTINE GRANAL 2 aaa ee 15 3 5 A sample SUBROUTINE JANAL ee 16 3 6 A sample SUBROUTINE HANAL 2 a a s ee 17 4 1 Typical MERLIN padel Q ubus 0 Q at o E h w RO WO NU w A a 22 4 2 Usage of the MERLIN flags rr rr sr saa ss s s s os s 30 5 1 The objective function for the sample curve fit o 34 5 2 The Jacobian matrix for the sample curve fit 2 o 35 5 3 First partial derivatives for the sample curve fit o 35 5 4 The Hessian matrix for the sample curve fit e r s 36 6 L The INIT panel a zs ss ao e ku bbe kup Lee eae A 40 6 2 Fhe PICK Panel risa a Ge Gh da aa ad 42 6 3 Th ROLL panel bea a p p ab ee oe 2 SUR N 45 6 4 Th SIMPLEX panel lssi aseri oe a A A a ae a eG ae 47 6 0 The BFGS paneli Serto easi et o AR a AA a we la 49 6 6 The DEP panels i458 ween isr di aa i an ia a ata NG Gs 51 6 7 The TOLMIN panel s s ss a Soy a tom ate ok eo eR we ee Q 3 QUQ 52 6 8 Phe TRUST panel im AA a ae ee ee ia us 53 6 9 The CONGRA panel ee QIs 56 6 10 THe LEVE panelo ir pe Bie Gee ee Bw de a e s ee GS 58 6 11 The AUTO panels e ee aie Bee Bh we Sw 3 ee ae BG ae oe A a 59 0 12 The ACCUM panel A es wk ee A A ee Gk 60 6 13 The HESSTAN panels ison ace eg odes Se ee ee eGo 2 eas E A 65 6 14 The MAD panel s a s od s ah oe di o al 67 Xi xii 6 15 6 16 6 17
21. A RAR e 139 SUBROUTINE GETTRG 0403 ii A Pa On U a a wi sg a A ee ee 139 SUBROUTINE SETADE s s 2 c s og yes a a qas Qupa we a w 140 FUNCTION NUNIT Su sva ia ah A ie a A Ew Sa a MY 140 SUBROUTINE BACKUP 60808 o Sea e a A SOY 141 FUNCTION TSIAE O uu ae Wo wae a a Qallpa g AS as se SUS 141 FUNGLDIONZAGS se ee agag a r m a E va a ala Q ua Q Q OS See 142 SUBROUTINE LSQFGN isig y z ata a A au Uw Bs Be GY 142 A MERLIN Quick Reference 143 vili Contents List of Tables 2 1 4 1 4 2 4 3 4 4 5 1 5 2 8 1 Some systems under which MERLIN was successfully installed 8 Shared parameter properties used in index specifications 22 Using an initial Hessian approximation r r r 0 eee ee s 26 Sample file MACROF with two macros e e sa e e e e s e s 27 Sample macro that expects two arguments e s 27 Data points to be fitted for the sample curve fit 0 00000008 34 A complete MERLIN session for the curve fit example User input appears underlined 37 Default values for all configuration directives o r r r r r e r 103 1x List of Tables List of Figures 2 1 Sample installer definitions file ee ee 7 2 2 Sample configuration file ua u m u S eee a we Ge 10 3 1 A sample main program 2 a 13 3 2 A sample FUNCTION FUNMIN aaa aaa ee 14 3 3 A sample SUBROUTINE SUBSUM 2 2 2 02
22. GETX X REAL X Purpose Returns the current values of all the minimization parameters Arguments X input output The current values of the minimization parameters with X i corresponding to parameter x Array X should have at least N storage locations available 9 1 2 SUBROUTINE GETX1 Definition SUBROUTINE GETX1 I XI INTEGER I REAL XI Purpose Returns the current value of one of the minimization parameters Arguments I input Index of the minimization parameter to be returned e XI output The value of the I minimization parameter 9 1 3 SUBROUTINE SETX Definition SUBROUTINE SETX X REAL X Parameter related glue routines 117 Purpose Sets the current values of all the minimization parameters This routine should always be used in conjunction with SUBROUTINE SETVAL so that the current value of the objective function corresponds to the current values of the minimization parameters Arguments e X input The values to set to the minimization parameters with X 1 corresponding to zi The values X 2 should lie within their corresponding bounds Moreover you are not allowed to assign a value different than the current one to a fixed parameter 9 1 4 SUBROUTINE SETX1 Definition SUBROUTINE SETX1 I XI INTEGER I REAL XI Purpose Sets the current value of one of the minimization parameters Arguments I input Index of the parameter to set e XI input The value to set to para
23. L a de ee tus de RCT tod 44 0 29 IITEES ir ee ted ee Ge ek oi ti il Rhee 5 A u A 44 626 RESET Ii bee ae aha a Be Soe eh eet a te gt 45 6 3 Minimization related commands 000 eee e e e s s e s 45 62321 ROLL 2 y de Be yta ss a hos Qu 2 Yk S She Q bee A Q Yi 45 06 52 SIMPLEX o 2 Ken geal geen E Ae oe ew a ma a uq 46 6 3 3 BEGGS 22 2 a BUNS uh n E Ae Soto 0 ow E ee eee tele ES 49 6 324 DEP A SA A ea oe deel aon ett ei ae a 51 6 30 FOLMIN z Z a A AA A Bae a A a is fs 51 0 330 RUSSEL a obs ios 53 6 3 1 UCONGRA gt ls ee ia Soe a A REA AAA G S 55 O A ka a on NO A O 58 6 39 AUTO pu sl ae ha ee a ls aa Ye daa a la da 59 03 LO tACCUMI ut A e li ta li all 60 G31 TARGETA o A a g 61 623312 NOTARGET e ei ee kes ke tf 62 Pordo ADJUST 2 YS ERA AR Gee PG a eS gh ek 2 Eee 62 Contents 6 4 6 5 6 6 6 7 6 8 111 0314 STEPALL t g you eh a o O a a eed h ee wl s asl E 62 OSS STEP a A a ee S 62 6 3 16 STEPDIS z C ate A ee Ae ee a Cb S ae Be fs 62 Flags and related commands 020200000222 ee eae 62 CAT FLAG doei t u a SSE Ae ete 3 2 ee EAL SG Ge eS 62 6 4 23 SEBAGD ES SCO eet A Gate ae ae oe fee Pde uuu yt real ah cess Ge gc 63 64 37 SEELAG oia aa eee a wks b we ee ae ale areal eee wes 63 6 43 CELAGDES 2002 Sa hE a ki Addie a tii Gece Bute ed eat tk ad 63 Modes of operation and related commands 2 02 020004 63 6 5 1 FAST QUAD NUMER ANAL 63
24. LNI4dA TIVH INTYd TIAA 3orido ue souya pubumoo boda DOTIdA suorjdo NITHAJN D sn sso utos 499 puounuo2 Jaund TOHINOD asessou Aue sejds q abossaw uv QHOA UISTURTPOUT JOISTY OY s qesrp s qeur pupwuiwos jauvd KYOLSIH STeAIOJUL 99u pUuoo s l1e no e O 19Pput AONACTANOOD XIIJEUL SJUBTILAO Y SIPPO puvwwo und HONVIYUVADO ure1301d TOW P9TIduro e Jo UOTJNIEXe s yenru ajyf apooyaatqo TOWNNNY aouenbes UOTPONAJSUOD OLDE Y s 1euruu YAO aouenbes UOTPONIJSUOD OLDEUL Y So eTHUT DHOVH SpueUIWIOD NITYAN e Sst LSIT puewwo NITYA Aue 10 s x9 doy sonss puvwwod ATHH LONOACIH JO PAP oy sjeouey IVA 9 Y Y 0 NANO NITHAJA SIO9MPOY aNHddV 21404794 LAOAGIH ay V 03 sioyourexed poued soya gt pupunuoo J upd wvu anda snyeqys pued oy s ejdsiq pupwwuoo jaund SALVLSd 92U949J9H YON NITUATA
25. PDUMP file_name panel_name panel_namez Purpose Writes to a file the current values of the parameters of one or more panel commands The file can be used later as a macro to restore the values of the panel parameters If no panel names are present in the command line the parameters of all MERLIN panel commands are written to the file 82 Command description 6 11 Output redirection and related commands Almost all MERLIN commands produce output This output can be redirected to a file using the Unix like gt and gt gt redirection symbols command argument argumenta gt filename will dispose the command s output to the file filename The file is overwritten command argument argumenta gt gt filename will append the command s output to the file file name 6 11 1 HIDEOUT Syntax classification UNC Syntax HIDEOUT filename APPEND Purpose Redirects all subsequent MERLIN output to the specified file The optional argument APPEND causes HIDEOUT to append the output to the file instead of overwriting it The effect of a HIDEOUT command is canceled by REVEAL Nested pairs of HIDEOUT REVEAL commands are allowed 6 11 2 REVEAL Syntax classification SIC Purpose Cancels the effect of the most recent HIDEOUT command 6 12 Macro and MCL related commands 6 12 1 MACRO Syntax classification SIC Purpose MACRO is an interactive command that assists the user in preparing a macro It initiates a mac
26. accumulated INFO Result code Possible values are e 0 The command terminated normally e 1 An end of file condition occurred in the input file while reading the panel parameters e 2 Some other error occurred for example some panel parameters are incorrect 6 3 11 TARGET Syntax classification UNC Syntax TARGET target_value Purpose Sets the target value used as a termination criterion by the optimization algorithms 62 Command description 6 3 12 NOTARGET Syntax classification SIC Purpose Clears a target value earlier set by a TARGET command 6 3 13 ADJUST Syntax classification SIC Purpose Constructs search steps for the ROLL method without using any gradient information It is based on the alternating variables method In addition ADJUST performs a minor optimization 6 3 14 STEPALL Syntax classification SIC Purpose Constructs search steps for the ROLL method using gradient information It is based on the method of steepest descent In addition STEPALL performs a minor optimization 6 3 15 STEP Syntax classification RAVAC Purpose Facilitates setting the search steps for the ROLL method Examples To set the step for the z variable to 0 1 and for the variables zs through z to 2 5 use the following STEP 1 0 1 3 6 2 5 6 3 16 STEPDIS Syntax classification RAC Purpose Displays the current search steps for the ROLL method 6 4 Flags and related commands 6 4 1 FLAG Syntax c
27. appropriate function p x such that y p t Vi 1 2 M We model the function p t p t a1 a2 an with parameters aj i 1 2 N which will be varied so as to achieve the above goal Equivalently we may claim that this corresponds to minimizing the following objective function with respect to the ai s M M F a1 a2 an y p ti a1 02 an gt fo a1 a2 ay l 1 To refer to a specific example consider the 20 points shown in table 5 1 and try to fit them with p t Q1 a2 as a4 01 azt azt at The Jacobian the gradient and the Hessian are given by m Si gi 2 gt fiti i l m k j 2 CR 2 t i 1 The Fortran 77 code for the subroutines SUBSUM JANAL GRANAL and HANAL is shown in figures 5 1 5 2 5 3 and 5 4 correspondingly We assume that the data points reside in a file named datafile with contents as shown in table 5 1 A complete MERLIN session for this example is shown in table 5 2 33 34 XA XX 3 Curve fitting A complete example 3 69619 8 37241 3 57096 i 9 43215 3 60643 6 10 58280 3 78799 8 11 82240 4 10364 0 13 14940 4 54358 2 14 56230 5 09979 4 16 06010 5 76569 6 17 64200 6 53590 8 19 30710 7 40601 0 21 05490 O AON OT PW NY Hu o Table 5 1 Data points to be fitted for the sample curve fit SUBROUTINE SUBSUM M N X F IMPLICIT DOUBLE PRECISION A H 0 Z SAVE PARAMETER NDATA 20 DIMENSION X
28. behave identically with the exception that their values can be reset to zero by the user via the RESET command This can be quite convenient when a comparison among different methods or strategies is sought 4 11 MERLIN files MERLIN uses ordinary disk files to store information during the minimization process The smallest unit of information stored in a MERLIN file is called a record It consists of N 1 entries one for each minimization parameter containing its value symbolic name fix status and lower and upper bound The last entry contains the corresponding value of the objective function Two types of files are handled by MERLIN Text files where all the information is stored as human readable ASCII characters They are implemented in Fortran using formatted sequential files Although updating the contents of a text file can be quite slow the file is portable across different MERLIN files 31 computer platforms On the other hand there are binary files where information is stored in machine readable form They are implemented in Fortran using unformatted direct access files Updating the contents of such a file is fast even for large files The file however cannot be transfered in a different computer system Text is the default type for all file operations 32 The MERLIN Operating System Chapter 5 Curve fitting A complete example Suppose we have the points t yi 1 1 2 M and we want to construct an
29. command currently being executed e SVAL input A string to be associated with the keyword e LES input Effective length of SVAL e IERR output An error code indicating success or failure Possible values are IERR 0 The routine completed successfully IERR 1 The panel description file indicates that the value of SVAL is not allowed for the given keyword 9 2 10 SUBROUTINE SETPPI Definition SUBROUTINE SETPPI PANEL KEY IVAL IERR CHARACTER PANEL KEY INTEGER IVAL IERR Panel related glue routines 127 Purpose Subroutine SETPPI assigns the integer number IVAL to the keyword KEY in the panel specified by PANEL Arguments e PANEL input Name of the panel that contains the specified keyword e KEY input The keyword to be associated with the integer value e IVAL input An integer value to be associated with the keyword e IERR output An error code indicating success or failure Possible values are IERR 0 The routine completed successfully IERR 1 The panel description file indicates that the value of IVAL is not allowed for the given keyword 9 2 11 SUBROUTINE SETPPR Definition SUBROUTINE SETPPR PANEL KEY RVAL IERR CHARACTER PANEL KEY REAL RVAL INTEGER IERR Purpose Subroutine SETPPR assigns the floating point number RVAL to the keyword KEY in the panel specified by PANEL Arguments e PANEL input Name of the panel that contains the specified keyword e KEY input The
30. e TEXT fora MERLIN text file Information is stored in human readable ASCII form Slower but portable e BIN for a MERLIN binary file Information is stored in binary machine dependent form Faster but less portable Specifies the amount of information that is kept in a backup file Allowed values are e NO Backups are not performed e LAST The most recent backup record overwrites the previous contents of the backup file e FULL The backup records are appended to the end of the backup file Specifies when a backup record is to be written to the backup file Allowed values are eM A backup record is written when a minimization routine terminates eX A backup record is written each time the minimization parameters are assigned new values through POINT INIT or PICK eD A backup record is written each time the fix status symbolic name upper or lower bounds of a parameter is changed 70 Command description eL A backup record is written each time a minimization routine discovers a new lower function value This setting is only recommended for extremely time consuming minimization sessions Any combination of the above values is allowed SAFE Specifies whether the slow but safe backup method should be used Allowed values are e YES Each time a backup record is written to the backup file its contents are flushed to disk thus preventing loss of backup records if the program terminates ab normally e NO Just writ
31. function drop in two successive iterations is less than FTOL The number of BFGS iterations to perform A value of 1 allows an unlimited number of iterations Specifies whether the MERLIN Automatic Derivatives are to be used when approximating the gradient vector Allowed values are e ON The MERLIN Automatic Derivatives are to be used e OFF Use the current derivative mode Determines how to obtain the gradient vector for the initial current point Allowed values are e 0 Do not use the values in the gradient cache Recalculate the whole gradient vector e 1 Instead of recalculating the gradient vector use the values in the gradient cache Determines the initial approximation to the Hessian matrix Allowed values are e0 The initial approximation is set to be the unit matrix e 1 The approximation from a previous BFGS DFP TRUST or HESSIAN command is used Determines the initial trust region radius Allowed values are e 0 The trust region radius is set equal to 2 lg e 1 The most recent value for the radius is used The p parameter used in the termination criteria for the line search This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL prog
32. handled as well Arguments e ICODE output An error code indicating success or failure Possible values are ICODE 0 The routine successfully processed all changes to the panel parameters Utility glue routines 129 ICODE 1 An end of file condition was encountered while trying to read from the MERLIN input file ICODE any other value Some other error has occurred for example the given value for a keyword was out of the allowed range 9 3 Utility glue routines 9 3 1 SUBROUTINE UPPER Definition SUBROUTINE UPPER CHA LL CHARACTER CHA INTEGER LL Purpose Converts a string of characters to upper case Assumes the ASCII character set Arguments e CHA input output On input the characters to be converted On output lower case characters are converted to their upper case equivalents e LL input Effective length of CHA 9 3 2 SUBROUTINE I2STR Definition SUBROUTINE I2STR N STR LES INTEGER N LES CHARACTER STR Purpose Converts an integer to its string representation Arguments e N input The integer to be converted e STR output Character variable containing the string representation of N One must supply adequate storage e LES output Effective length of STR 130 MERLIN glue routines 9 3 3 SUBROUTINE TOINT Definition Purpose Arguments SUBROUTINE TOINT STR LE N IERR CHARACTER STR INTEGER LE N IERR Converts an integer from its st
33. install f e merlin d e sample d e HELP e PDESC e mcl d e manual ps The MERLIN MCL installation program Source code for the MERLIN package Does not contain any of the user written routines Empty plug in modules for extending MERLIN s functionality are included here Sample user written routines A sample main program and the source code for the Rosenbrock function in both forms general and sum of squares It also contains the source for the gradient Hessian and Jacobian The MERLIN help file The panel description file It used by both MERLIN and MCL in order to correctly recognize panel commands Source code for the MCL compiler The present manual in PostScript form Note that the files merlin d sample d and mcl d must be processed by the installer program before they can be actually compiled The procedure is explained in the following sections 5 6 Installation and configuration 2 2 Installation 2 2 1 Why an installation procedure The MERLIN MCL source code contains a number of parameters and options that must be cus tomized in order for the programs to operate correctly Some of them can be set at run time while others must be hard coded in the Fortran source An example of the later is the maximum number of minimization parameters which affects the size of the internal one dimensional MERLIN work arrays and the precision single or double of floating point numbers Although we could provi
34. is omitted the help text is associated with the command itself help_tezt A multi line help text All lines in between help and end including blank lines and lines starting with the percent character are considered as part of the help text Chapter 8 The MERLIN MCL configuration file 8 1 General description The purpose of the configuration file is to set system dependent parameters such as the largest floating point number and control the various defaults such as the printout level processing mode etc in a portable way The configuration file is read by both MERLIN and MCL and its default name CONFIG can be changed during installation Each line of the configuration file contains a configuration directive and optionally one or more parameters directive parameter parametera parameter Lines starting with the percent character comments and blank lines are ignored Directives and parameters are case insensitive with the exception of filenames which must adhere to the local operating system conventions and can be up to 80 characters long Arguments with space or tab characters must be enclosed in a pair of single quotes A quote is generated using the escape sequence Leading and trailing spaces and tabs are ignored outside a pair of single quotes In case of multiple instances of a directive the last one takes effect PLUG is an exception where multiple PLUG directives are used to define various user plug
35. proceeds with a syntax check of the following data otherwise issues a warning message and prompts for another command Blank lines and comment lines do not cause warnings A comment line is any line that its first non blank character is the symbol Comment lines can be used for documentation purposes and are useful inside macros and in batch processing where an input file is prepared containing all the commands to be processed Supplying input 21 The input arguments are acquired using a mechanism called the one line input The required input must be supplied by the user in a line of the form item ttema items ttemk Items are separated by one or more spaces The significance of each item varies according to the specific MERLIN command requesting the input Commands that manipulate the minimization parameters use a scheme to specify which parameters are to be manipulated This specification scheme uses 1 Parameter indices To operate on parameter zx its index is used For example the entry FIX 1 5 7 fixes variables 11 25 and z to their current values 2 Parameter names A name corresponds to an index It is just an auxiliary mnemonic alternative Hence names and indices may be used invariably Names can be set using the GODFATHER command 3 Parameter ranges A range is denoted as index index and specifies all parameters Zindex through Linders For example the entry FIX 1 5 fixes the parameters x through
36. requesting MCL program the number of lines written to the file The third empty plug in subroutine is used for this example SUBROUTINE PLUG3 CALL PEXA END The name of the plug in PEXA is declared in the configuration file as PLUG 3 PEXA The PEXA panel as presented by MERLIN when the command is invoked is shown in figure 7 8 The panel uses three keywords FROM TO and FILE The following section describes the format of the panel description file and explains how to make the appropriate entries Part of the panel description file that correspond to the PEXA sample plug in is shown in figure 7 7 7 7 The panel description file All MERLIN panels and their corresponding keywords along with their default values are stored in the panel description file Its default name is PDESC and can be changed through the configu ration directive PDESC_FILE MERLIN commands and user plug in modules share the same panel description file Note that the panel description file must be present in order for MERLIN to operate The format of the panel description file is explained in the following sections Lines starting with comments and blank lines are ignored 7 7 1 Declaring the panel name The description of a panel starts with a panel line and extends until another panel line or the end of the description file is encountered The format of a panel line is panel panel_name panel_status panellname The MERLIN command that this panel c
37. reside in the MERLIN help file named HELP The structure of the help file is shown in figure 7 3 help_text help_tertz are multi line help texts that appear whenever requested by a HELP command initial_help_tert appears whenever a HELP command without any arguments is issued Part of the help file that corresponds to the sample plug in module NEWSH is shown in figure 7 4 The default name can be changed using the HELP_FILE configuration directive 94 Extensions initial_help_text x xcommand_name z help_text x command_names help_texta Figure 7 3 The structure of the MERLIN help file NEWSH NEWSH is a sample plug in module that demonstrates the use of the Merlin glue routines It does not require any command line arguments and its output resembles the SHORTDIS command Figure 7 4 Help text for the sample plug in module NEWSH 7 5 Plug ins with command line arguments Plug in modules can take advantage of any arguments in the MERLIN command line A more elaborate example is presented in figure 7 5 a plug in module that will write the value of the parameters their names if any and their first partial derivatives to a user specified file The file name will be given as a command line argument If we use the second empty plug in subroutine SUBROUTINE PLUG2 CALL FILESH END and choose the name FILEDIS then an appropriate entry in the configuration file would be PLUG 2 FILEDIS The plug in modu
38. setting the IQUIT return flag to 10 action can be rewind MERLIN rewinds and re reads the input file ignore MERLIN ignores the end of file condition and continues reading from the input file return MERLIN immediately returns to the calling program setting the IQUIT return flag to 10 Default If this directive is omitted 1t defaults to ONEOF return Used by MERLIN only Examples ONEOF ignore 8 3 12 FILE Syntax FILE filename file_contents END Purpose Allows the contents of an arbitrary file to be included in the configuration file Upon MERLIN startup all lines in between FILE and END are copied in the file file_name If filename exists already its contents are overwritten This directive can be used in conjunction with the PROLOG directive Miscellaneous directives 111 Default Used by Examples Three is no default value If this directive is omitted no file is created MERLIN and MCL FILE prl POINT 1 8 4 SHORTDIS END 8 4 Miscellaneous directives 8 4 1 MODE Syntax Purpose Default Used by Examples MODE processing_mode Specifies that MERLIN should start in interactive iaf or batch batch processing mode processing mode can be either iaf or batch The processing mode can be changed by the IAF and BATCH commands If this directive is omitted it defaults to MODE iaf MERLIN only MODE batch 8 4 2 PROLOG Syntax Purpose Default Used by
39. should read its input from filename instead of the standard input unit None If this directive is omitted MERLIN reads its input from the standard input unit MERLIN only INPUT_FILE test INPUT_FILE sample input INPUT_FILE c merlin in sample in 8 2 3 OUTPUT_FILE Syntax Purpose Default Used by Examples OUTPUT_FILE filename APPEND OUTPUT_FILE specifies that MERLIN should dispose its output to filename instead of the standard output unit If the optional argument APPEND is present and file_name exists already output will be appended at the end of the file None If this directive is omitted MERLIN disposes its output to the standard output unit MERLIN only OUTPUT_FILE fit out append OUTPUT_FILE results run01 8 2 4 INPUT_UNIT Syntax Purpose Default Used by Examples INPUT_UNIT untt_number INPUT_UNIT specifies the Fortran unit number that refers to the standard input device keyboard i e a Fortran statement of the form READ unit_znumber x x should be able to receive input from the keyboard If this directive is omitted unit_number defaults to 5 This value is suitable for most compilers running under Unix MERLIN only INPUT_UNIT 9 Directives that control MERLIN input output 105 8 2 5 OUTPUT_UNIT Syntax Purpose Default Used by Examples OUTPUT_UNIT unit_number OUTPUT_UNIT specifies the Fortran unit number that refers to the standar
40. that according to installation o refers to either real or double precision arithmetic If this directive is omitted o defaults to 107 which is suitable for most computers in single precision MERLIN only SMALLER 1 E 300 8 4 7 MACHINE_DIGITS Syntax Purpose Default Used by Examples MACHINE_DIGITS n Specifies that during floating point operation approximately n significant digits are taken into account Note that according to installation n refers to either real or double precision arithmetic The default value is determined and printed at MERLIN startup Use this directive if for some reason MERLIN determines incorrectly the machine precision MERLIN only MACHINE_DIGITS 7 MACHINE_DIGITS 15 114 The MERLIN MCL configuration file Chapter 9 MERLIN glue routines The following is a complete list of all MERLIN glue routines Their purpose is to provide a standard programming interface to the internal MERLIN data structures By using the glue routines instead of directly accessing the internal data structures one avoids any knowledge of the internals of the MERLIN source Furthermore he ensures compatibility of any plug in modules with future MERLIN versions since the internal structures may change the glue routines will not Most of the glue routines can be roughly classified as get or set routines Get routines return information from the MERLIN run time environment Set routines
41. the actual values in place of the installer macros and output the full Fortran 77 source ready for compilation 3 The last step is compilation of the package The installer cannot do this for you since invoking a compiler is a system dependent task Compilation of the processed MERLIN MCL source is quite straightforward MCL is an autonomous program and must be compiled alone For example on a Unix system 77 O mcl f o mcl MERLIN should be compiled and linked with the appropriate user written routines The distribution provides a sample 8 Installation and configuration SUN Ultra 2 SunOs 5 5 1 77 4 0 SUN SparcClassic SunOS 4 1 3C 77 1 4 SGI Power Challenge M IRIX 6 2 77 7 0 Control Data 4680 EP IX 1 4 3 77 2 20 PC 486 MS Windows 95 MS Fortran PowerStation 4 0 PC 486 Linux 2 0 18 f2c 19950110 gcc 2 7 0 Macintosh Performa 6320 MacOS 7 5 1 MPW 3 3 LS Fortran 3 3 Macintosh LC475 MacOS 7 1 Absoft Mac Fortran 2 4 Table 2 1 Some systems under which MERLIN was successfully installed 77 0 c merlin f 77 0 c sample f 77 o merlin merlin o sample o Make sure the panel description file PDESC is present before attempting to run the MERLIN or MCL executables Using the above procedure we were able to successfully install MERLIN in a number of different systems in single and double precision Some of them are listed in table 2 1 2 2 3 The complete list of installer macros All of the follo
42. tives e A Use the user supplied SUBROUTINE HANAL that returns the Hessian matrix The file to write to or read from the Hessian matrix This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended 6 5 5 GRADDIS Syntax classification RAC Purpose Displays the values of the gradient components and the mode used for their calculation Examples GRADDIS F 6 5 6 GRADCHECK Syntax classification UNC Syntax GRADCHECK mode modez index_specification GRADCHECK mode index_specification Purpose Checks the derivatives calculated using mode against those calculated using mode and displays the result for the parameters specified by the indez_specification If the second form of the command is used the derivatives are checked against the current derivative mode mode modeg and mode can be one of ANAL FAST QUAD or NUMER If no indez_specification is given the results are displayed for all minimization parameters Examples GRADCHECK ANAL QUAD GRADCHECK ANAL NUMER 1 6 Modes of operation and related commands 67 Ind Keyword Description Value Allowed values 1 FQ Fast gt Quad threshold 0 0001 0 lt real lt 1 2 QN Quad gt Numer threshold 1 E 7 0 lt real lt 1 3 RECALC Re
43. 025 2 MIXED oss 5 A a Bok ES Gens Ba A Bee Boe i Ee aB 64 6 9 3 JNUMER JANAR 22 2 es 240 Does ooh Meee bo bees eee 64 604 HESSIAN 5 eecq ete a doe SS eek Ae EA ee A 64 6 0 5 GRADDIS S 2 2 wast u dee ae Shad ed Bodh te a eee a ed ees oe a kS 66 60 67 GRADCHECK ecos tot te ee pn aaa SE ea Bee a AR We E E 66 0 5 JCOMPAREO Ls Ses oon a ee ea Bo a A de ee ahs 67 00 90 GNORM u ansa Beh weve ate a AA AA a a te ee 67 6 5 9 MAD og 222 2 ee eh Q S u Q W ee te ee we ede 2 Q 2 67 6 5 10 TAR BATCH uy as Go ae eo ea ae ee ea Ma 68 6 5 11 NOBACK LASTBACK FULLBACK 20 0002 s s s s s 68 60 12 BACKUP seca conti aya a S SiR wae ack bie wee Be as 69 6 5 13 NOPRINT HALFPRINT FULLPRINT e e s s s s 70 Gro 14 GENERAL SOS at A A A a de 70 6 0215 EVALUATE NOEVAL apat og odd a its A a eee es Poet 71 62000 MODEDTS 1 seth i a ahs hie hous High en Ua Maid cae e ad 71 Got EMITS specs 83 Lethe S n ee a yee A Re he es ee PG ee ae A 9 71 Aliasing and related commands 2 0 sss ee 71 6 021 ALTAS fect O nate A A RA A at abe ae Wee thy eae we SE e 71 6 6 27 CUNALTAS 2 2 2 22 214 Sed bk ea ble bbe S bes Pele on 71 60 39 ALTASDIS oro a A eS ES ek A PAR Oe Re A 72 Termination and post processing 2 e 72 Orel STOP 2 G acampaq SS eye ee es Pa apu on ed gc yu Ms 72 6 2 RETURN sot Sea et se he ee ee ee Bo ed ee ce a a 72 Sis UR A OR ama nay STAG anqa re ee ee 72 File manipulation
44. C Number of calls Any int gt 1 PRINT Printout level 0 1 2 USEV Use Recalculate vertices 1 0 INIT Initialization Disp LS 1 2 DISP Displacement percent Any real gt LSNOC Line search calls Any int gt LSTOL Line search tolerance real FTOL Simplex tolerance 0 real XTOL X convergence criterion 0 lt real ITER Iterations 1 Inf Any int gt ALPHA Reflection factor Any real gt O BETA Contraction factor 0 lt real lt 1 GAMMA Expansion factor Any real gt 1 USEV INIT DISP LSNOC LSTOL FTOL CANCEL Cancel Proceed 0 1 Figure 6 4 The SIMPLEX panel e 2 Display function and parameter values as well Specifies how SIMPLEX should obtain its initial vertices Allowed values are e 0 Initialize the simplex vertices according to the setting of INIT e 1 Use the vertices from a previous SIMPLEX invocation Specifies the method of initializing the simplex vertices when USEV is set to 0 Allowed values are el Usea displacement along each direction The relative distance is specified by DISP e 2 Perform a line search along each direction and use the resulting minimum as a vertex Specifies the relative distance along each direction when INIT 1 is selected More specifically vertex i is set to the current point with the th parameter being zi DISP z The maximum number of function calls that are allowed in the line search The line search termination
45. CK GRADCHECK HIDEOUT JCOMPARE LIST MEMO NOPRINT PICK RDEMARGIN ROLL STEPALL TOLMIN 85 FULLPRINT GRADDIS HISTORY JNUMER LMARGIN MIXED NOTARGET POINT RESET RUNMCL STEPDIS TRUST Use the HELP command to obtain more information Figure 6 22 Output from the LIST command Syntax POINT index_specification value Description POINT assigns values to the minimization parameters MCL equivalent POINT X index value X index value Examples POINT 1 1 5 2 3 65 POINT 1 8 12 5 See also SHORTDIS INIT Figure 6 23 Sample output from the HELP command 86 Command description tolmin lt cr gt Ind Keyword Description Allowed values 1 NOC Number of calls Any int gt 1 2 PRINT Printout level 0 1 2 3 ACC Termination accuracy 0 lt real lt 1 4 MAD Automatic derivatives On 0ff 5 CANCEL Cancel Proceed Enter changes mad lt cr gt Specifies whether the Merlin Automatic Derivatives are to be used when approximating the gradient vector Allowed values are ON The Merlin Automatic Derivatives are to be used OFF Use the current derivative mode Figure 6 24 Requesting help on panel keywords 6 14 3 Help on panel keywords When a panel with several keywords appears one can obtain information for their meaning on line by entering a keyword or an index followed by a question mark As an example we list the user s input and the corresponding output in figure 6 24
46. L returned keywords are set by the plug in module and are accessible by an MCL program A single character indicating the keyword type i e what kind of values are associated with the keyword Possible keyword types are el eR ec The keyword is associated with integer numbers The keyword is associated with floating point numbers The keyword is associated with character strings MERLIN uses case in sensitive comparisons to determine whether an allowed value has been assigned to the keyword The keyword is associated with character strings MERLIN uses case sensi tive comparisons to determine whether an allowed value has been assigned to the keyword A description of the values allowed for the keyword in one of the following forms For keywords of type I or R an interval of allowed values in the form ls ll ul rs Is is either for an open interval or for a closed interval rs is either for an open interval or for a closed interval ll ul The lower and upper limits of the interval correspondingly They must be integer or floating point numbers according to the corre sponding keyword type The symbols inf and inf can be used to designate plus or minus infinity Note that always ll lt ul Examples 0 1 0 inf inf inf 0 5 2 5 10 10 A set of allowed values in the form 100 Extensions value values value Y The values in the set must be integer or floating point numbers or c
47. L commands The command HIDEOUT file redirects all subsequent output to the specified file until a REVEAL command is entered The file is overwritten To append to the specified file rather than overwriting it one must enter the following HIDEOUT file append Nested pairs of HIDEOUT REVEAL commands are allowed as well as commands with gt and gt gt redirection inside a HIDEOUT REVEAL block 4 4 Getting help Since MERLIN is designed primarily for interactive use it is equipped with an easy to use help system The user can request help on any MERLIN command The help texts include the command syntax a short description of the command and pointers to other relevant information The help system is facilitated by the HELP command Without any arguments it displays a help screen instructing the user how to request further help To get information about a specific command or topic use HELP with an argument for example HELP BFGS To get an alphabetic list of all MERLIN commands enter the command LIST Help is also available on the usage and meaning of the various keywords in the panel commands When prompted by a panel for changes enter the name of any keyword followed by a question mark for example PRINT The MERLIN help system can be easily extended if one wishes to add his own commands or topics or even enlarge the description of the already existing texts The procedure is described in detail in chapter 7
48. MCL programs set MCLMEM to 1 If during the installation process you specify that you intend to run MCL programs the default value 50000 is substituted otherwise MCLMEM is set to 1 The length of a character variable used as the MCL program buffer This buffer is supposed to hold the entire MERLIN object code during execution of an MCL program If you do not intend to run MCL programs set MCLBUF to 1 MCL programs will still run at a slower pace however Tf during the installation process you specify that you intend to run MCL programs the default value 50000 is substituted otherwise MCLBUF is set to 1 The maximum number of plug in modules The installer always sets MXPLUG to 50 You should not change the default value unless you are prepared to make the necessary modifications in the source code as well add empty plug ins CALL and GOTO statements etc 2 3 Configuration Although we made every effort to ensure the code is truly portable there is a small number of system dependent options that must be customized before MERLIN or MCL begins execution The most important ones are the input output unit numbers and an approximation of the largest and smallest positive distinguishable from zero floating point numbers your machine accepts The internal MERLIN defaults for these parameters are set in the source code to 5 6 10 and 10730 correspondingly adequate for most systems in single precision Any change to these paramete
49. MERLIN 3 0 User Manual D G Papageorgiou I N Demetropoulos Department of Chemistry LE Lagaris Department of Computer Science http nrt cs uoi gr merlin UNIVERSITY OF IOANNINA GREECE Contents 1 Introduction 1 1 1 What kind of problems MERLIN handles 00 0000004 1 112 Conventions lt 42222 sete DA A i a AA oid Yu S 2 LLL Py ping ss gasas s SOS a ed Po a EE ee de RR ee tes 2 1 225 sSymbolss ss ge eyes ya wo a a Ree ae wu BE ee Hae wh a eee Hod 2 2 Installation and configuration 5 231 ThE PIECES cion id hw a alquqa ie no a Vo ee 4 Ae we ee QQ 5 2 2 Installation tee AA a a a da 6 2 2 1 Why an installation procedure e 6 2 2 2 Running the installer program ee 6 2 2 3 The complete list of installer Macros o 8 223 CONSULTA e A of ae 9 3 User written programs 11 3 1 The main programy te 2 tes A eB ds m AA ke Poe SG 11 3 2 The objective function General forM e 12 3 3 The objective function Sum of squares form e e 14 3 4 Phe eradient Vector dia A a a a vee Ge 15 3 5 The Jacobian matrix 15 3 0 The Hessian Matlab A ge ee Se ee hs 16 of Important notes 4 0 66 EA eee ewe ae E k de Bea Y h S eS 17 4 The MERLIN Operating System 19 4l Commands cal fait 2 Gece aw oe we Ae eek a WS i ei ee e Y 19 4 2 Supplying inputis sio a Ee Be ee ee ee Saa RS Gl he wee 20 43 gt Output handling ut
50. N F M COMMON XYDATA XDATA NDATA YDATA NDATA DATA ITRIC O The following block if is executed only once i e when the subroutine is called for the first time IF ITRIC EQ 0 THEN ITRIC 1 OPEN 1 FILE datafile DO 1 I 1 M READ 1 XDATA I YDATA I CLOSE 1 END IF DO 2 I 1 M XD XDATACI YMODEL X 1 X 2 XD X 3 XD 2 X 4 XD 3 F I YDATACI YMODEL CONTINUE END Figure 5 1 The objective function for the sample curve fit 35 SUBROUTINE JANAL M N X FJ LD IMPLICIT DOUBLE PRECISION A H 0 Z PARAMETER NDATA 20 DIMENSION X N FJ LD N COMMON XYDATA XDATA NDATA YDATA NDATA DO 2 J 1 N DO 2 I 1 M FJ I J XDATA I J 1 END Figure 5 2 The Jacobian matrix for the sample curve fit SUBROUTINE GRANAL N X GRAD IMPLICIT DOUBLE PRECISION A H 0 Z PARAMETER NDATA 20 DIMENSION X N GRAD N COMMON XYDATA XDATA NDATA YDATA NDATA DO 3 J 1 N GSUM O DO 2 I 1 NDATA XD XDATA I YMODEL X 1 X 2 XD X 3 XDx x 2 X 4 XDx x 3 FI YDATA 1 YMODEL GSUM GSUM 2x FTIx XDx x J 1 CONTINUE GRAD J GSUM CONTINUE END Figure 5 3 First partial derivatives for the sample curve fit Curve fitting A complete example SUBROUTINE HANAL H LD N X IMPLICIT DOUBLE PRECISION A H 0 Z PARAMETER NDATA 20 COMMON XYDATA XDATA NDATA YDATA NDATA DIMENSION X N H LD N DO 1 I 1 N DO 1 J 1 1 HSUM 0 DO 2 K 1 NDATA H
51. N matrices e MERLIN commands Fortran code and I O data are printed using a monospaced font cr denotes keying the carriage return implies that preceding symbols may be repeated Optional items are enclosed in square brackets 1 2 2 Symbols e Nin The number of parameters dimensionality of the problem e f z The objective function e 7 The th component of z e f z The kth term entering in the calculation of the objective function when it has the form vies file eM The number of the squared terms involved in the above sum Conventions 3 g The gradient vector of the objective function V f z oJ The Jacobian matrix with Jij G The Hessian matrix with G eB An approximation to G eH An approximation to G e li ui The lower and upper bounds for x referred to as the left and right margins e The machine accuracy i e the approximately largest constant such that in machine precision 1 7 is equal to 1 Introduction Chapter 2 Installation and configuration 2 1 The pieces MERLIN is under continuous development The authors make several minor revisions from time to time that enhance its performance and functionality However these revisions alone do not justify a new publication For this reason the latest revision of the MERLIN MCL package is available from http nrt cs uoi gr merlin The complete distribution contains the following files e
52. O 1 inf 1 Index to end to I FILE S any 2SAMPLE File to write to I 1 inf 1 Lines written LINES HELP The PEXA plug in module disposes some of the minimization parameters in a file END HELP FROM FROM specifies the index to start writing from END HELP TO TO specifies the index to end writing to END HELP FILE FILE specifies the file to write to END Figure 7 7 Part of the panel description file corresponding to the PEXA sample plug in module Ind Keyword Description Allowed value 1 FROM Index to begin from Any int gt 1 2 TO Index to end to Any int gt 1 3 FILE File to write to SAMPLE Any string Figure 7 8 The panel of the PEXA sample plug in module as presented by MERLIN The panel description file 99 7 7 2 Declaring the keywords After declaring the panel name all keywords that appear in the panel must be described If neces sary the description of a keyword can be split across several physical lines using the continuation character amp at the end of each continued line The description of a keyword has the form keyword keyword_type allowed_values default_value short_description keyword keyword_type allowed_values The keyword name It must be up to 10 characters long and is case insensitive It must be unique in the current panel Keywords of type I or R may be followed by a question mark to designated an MCL returned keyword The values of MC
53. PUT_FILE OUTPUT_FILE INPUT_UNIT OUTPUT UNIT INPUT_PRECONN OUTPUT_PRECONN HEADER PRINTOUT 8 3 File related directives 8 3 1 8 3 2 8 3 3 8 3 4 8 3 5 8 3 6 8 3 7 8 3 8 8 3 9 8 3 10 8 3 11 8 3 12 PDESC FILE MACRO FILE HELP_FILE MCL_ERROR_F ILE MCL_OBJECT_FILE HAS_APPEND SIZE_REAL SIZE_INT SIZE_CHAR UNIT_RANGE ONEOF 8 4 Miscellaneous directives 8 4 1 8 4 2 8 4 3 8 4 4 8 4 5 8 4 6 8 4 7 BIGGER SMALLER MACHINE_DIGITS 9 MERLIN glue routines 9 1 Parameter related glue routines 2 2 2 0 0 eres es ee eee 9 1 1 SUBROUTINE GETX 99 100 101 101 102 102 102 104 104 105 105 105 106 106 106 106 107 107 107 108 108 108 109 109 109 110 110 111 111 111 112 112 112 113 113 115 vi 9 2 9 3 9 4 Contents 92 SUBROUTINE GETAL o 2 s ua o a w tke Wa ew ee a 116 9 123 SUBROUTINE SETX ia a ee ee eek eee 34 9 116 9 14 SUBROUTINE SETX4 s u a Ae ed Oe Beate a 117 9 1 5 SUBROUTINE GETG U pre Qo ae wh a Go Pee ot Sek eee Soe 117 9 1 6 SUBROUTINE GEPGT A Se ees k eS Se LESSEE ES Be ER RAGES BOS 117 91 77 SUBRDUTINE GETHES 2 giois i a oR wR Oe OP eae ed ae a ek Gee 118 9 1 8 SUBROUTINE GETJAG ara ioe p eee Be a Ble wale eb gag 119 9 1 9 SUBROUTINE GETMAR e W O a ee ee uw 119 9 73 10 SUBROUTINE GETMR I S cise AR Re pe eg ee SA aed Ae a 120 YLIT SUB
54. Purpose Sets the current value of the objective function Arguments e VALUE input The current value of the objective function Note that this value must correspond to the current values of the minimization parameters for example those set by SUBROUTINE SETX 9 4 17 SUBROUTINE GETEVM Definition SUBROUTINE GETEVM IEV INTEGER IEV Purpose Returns the current function evaluation mode The function evaluation mode can be changed with the NOEVAL and EVALUATE commands Arguments e IEV output The function evaluation mode Possible values are IEV 0 Evaluation of the objective function has been disabled by a NOEVAL com mand IEV 1 Evaluation of the objective function is enabled Miscellaneous glue routines 139 9 4 18 SUBROUTINE GETFFO Definition SUBROUTINE GETFFO IFF INTEGER IFF Purpose Returns the form of the objective function The form of the objective function is chosen by initially supplying the appropriate subprogram FUNCTION FUNMIN or SUBROUTINE SUBSUM and then by choosing it by the GENERAL and SOS commands correspondingly Arguments e IFF output IFF indicates the form of the objective function Possible values are IFF 0 Command GENERAL has been issued indicating that the user has prepared the appropriate subprogram for a general function FUNCTION FUNMIN IFF 1 Command SOS has been issued indicating that the user has prepared the ap propriate subprogram for a sum of squares funct
55. QFCN Definition Purpose Arguments SUBROUTINE LSQFCN M N X F INTEGER M N REAL X N F M All MERLIN minimization methods that operate on functions that are sum of squares call this routine It contains a counter and updates some common block parameters Its value is set equal to the user supplied SUBROUTINE SUBSUM e M input Number of terms in the sum of squares e N input Dimensionality of the objective function e X input The minimization parameters with X i corresponding to zi e F output Partial terms of the sum of squares with F z corresponding to fi Appendix A MERLIN Quick Reference 143 sd s yoreos TIOU 09 SONJLA susissy anyon TIPUL dALs INJLA 193 189 VY SIeITD LA9YUVLON SPOYJOUL uonmezrtururtut OY 107 oNnTeA 193189 Y SJ98 anjon 196107 LADUVL Wose uonezrtururtu NADIV OY SeyOAUT puvwwo jaund Wnoov wyguosje uornezrururu OLNY of SexOAUT puvwwos jauod OLAV WY WOSTe UOTYEZIUMIUIW JATT 9Y SoyOAuT punwwos jaupd ANAT WY WOZTS UOTYEZIUMUIW XYATAWIS OY SexOAUT pubuo jaupd Xa 1dWIS WY UOSTe UOTYEZIWIUIW TIDY 9Y SexOAUT puvwwos jauod TIOUN IU IO3 0 UOTJeZIUITUIU YYDNOO ey SONOAUT puvwwo jauvd YHUDNOD IU IO3 0 UOTYRZTUITUTUL NIWTOL 9Y SONOAUT puvwwo 240d NIWIOL WJS uonezrururu LSNUL oy SoyOAUT puvwwo 2uod LSNUL WY WOZTe UOTYEZIWMUIW dAd oy SOJOAUT pupunuoo2 jauvod gad wyguosje UOTYEZIWIUIW SHAG 94 SONOAUT puounuoo2 jauod s948 CI INR ET OJ9Z 0 SI9JUNO Ted
56. ROUTINE GETPIX is ce he A o 120 9 112 SUBROUTINE GETEXL Z Z ge sl ee lens Boge ae Pee og ok EE 121 9 7 13 SUBROUTINE GETNAM v es to04 sae gly Papapis p u eM ee es 121 91 14 SUBROUTINE GETIT cusco doe a He See a ee Se ae 122 Panel related glue routines 2 2 ee ee n 122 9 21 SUBROUTINE GETE Le ca ae Gh e a he ee hae as ae SE Be 122 9 2 2 SUBROUTINE GETPR ccia s wna ee oe ee ea ee ee ee ewe oe 122 9 2 3 SUBROUTINE GETPS y s sas a Gk ae a a Ee U Re 123 9 2 4 SUBROUTINE GETPPI 2 Waqaspa sean e O 2 KOS WOO S UO ONG EQ 123 9 2 5 SUBROUTINE GETPPR voii o a uw aT a amia e U ee ea 124 9 26 SUBROUTINE GETPPS c a aus o wa a oe a gael a Gone SL a os 124 9 20 lt SUBROUTINE SETRI y cu sie al o SDK WO W SI TR Se 125 02e SUBROUTINE SETPBR I 2 X oo k was Sea A AA 125 9 2 9 SUBRDUTTINECSETPS ii Fa A A Gee y a u ST 126 YATO SUBROUTINE SETPPL y Z zy pa RA eho a amp hee Geos Poet ee 126 9 2 T1 SUBROUTINE SETPPR tio k ba SUP a a a de ul 127 9a TA SUBROUTINE SETPES 0 9 ogee AR op A E Pa ae ae a ua A 128 9 2 13 SUBROUTINE CHANGE orou s s de a ee AO we oe SO Sl 128 Utility elie TOULIDES cia te eh a sbg ee eo a a eee te Ses 129 9 351 SUBROUTINE UPPER s 2 5 Z ba k heh ble bbe S huk AES Pelee eee 129 9 3 2 SUBROUTINE TOS TRI S gee a kuy OS eee Ba Se ae ae eee Sa a Wee 129 9 333 SUBROUTINE TOENT Qu sega s u ay Be he Ae ae te sss Mh a bus 2 od 130 973 4 SUBROUTINE TOREAL ou 3
57. ROUTINE GETFIX Definition SUBROUTINE GETFIX IX INTEGER IX Parameter related glue routines 121 Purpose Returns the fix statuses for all the minimization parameters Arguments e IX output The fix statuses with IX i corresponding to the fix status of parameter zi Possible values are IXG O Parameter z is fixed IX 1 Parameter x is not fixed Array IX should have at least N storage locations available 9 1 12 SUBROUTINE GETFX1 Definition SUBROUTINE GETFX1 I IXI INTEGER I IXI Purpose Returns the fix status for one of the minimization parameters Arguments I input Index of the minimization parameter whose fix status is requested e IXI output Fix status for parameter x1 Possible values are IXI 0 Parameter zr is fixed IXI 1 Parameter zr is not fixed 9 1 13 SUBROUTINE GETNAM Definition SUBROUTINE GETNAM NAME CHARACTER NAME Purpose Returns the symbolic names of all the minimization parameters Symbolic names can be assigned using the GODFATHER command Arguments e NAME output NAME 1 stores the symbolic name of parameter z Array NAME should have at least N storage locations available each of them being at least 10 characters long If no symbolic name has been set for parameter zi NAME 2 is left blank 122 MERLIN glue routines 9 1 14 SUBROUTINE GETNM1 Definition SUBROUTINE GETNM1 I NAMEI INTEGER I CHARACTER NAMEI Pu
58. SUM HSUM 2 XDATA K I J 2 H I J HSUM CONTINUE END Figure 5 4 The Hessian matrix for the sample curve fit 37 Table 5 2 A complete MERLIN session for the curve fit example User input appears underlined Enter number of variables number of squared terms MERLIN 3 0 D G Papageorgiou I E Lagaris I N Demetropoulos University of Ioannina GREECE Email merlin nrt cs uoi gr Web http nrt cs uoi gr merlin The Merlin help file HELP is present The panel description file PDESC is present Use the help command to obtain on line information Number of terms Number of variables 4 Estimated machine s accuracy 1 E 15 Merlin uses SUBROUTINE SUBSUM as the objective function WARNING Initialize variables N N N Merlin is at your command sos Instruct MERLIN to use the sum of squares form sos Functional form has been set to sum of squares Merlin will be calling subroutine subsum WARNING Initialize variables N N N Merlin is at your command point 1 22 9 2 3 1 1 4 11 4 Enter a starting point POINT N Merlin is at your command janal Instruct MERLIN to use the user supplied code for the Jacobian JANAL N N N Merlin is at your command title Curve Fitting using a cubic polynomial Set a title for the problem TITLE Title is set to Curve fitting using a cubic polynomial N N N Merlin is at your command continued
59. TINE GETFLA I F INTEGER I REAL F Returns the value assigned to one of the MERLIN flags e I input Index of the flag whose value is requested e F output Value of the Ith flag 9 4 8 SUBROUTINE SETFLA Definition SUBROUTINE SETFLA I F INTEGER I Miscellaneous glue routines 135 REAL F Purpose Assigns a value to one of the MERLIN flags Arguments I input Index of the flag e F input Value to be assigned to the Ith flag 9 4 9 SUBROUTINE GETCFL Definition SUBROUTINE GETCFL I CFL INTEGER I CHARACTER CFL Purpose Returns the value of one of the MERLIN character flags Arguments e I input Index of the character flag whose value is requested e CFL output Value of the I character flag It should be at least 30 characters long 9 4 10 SUBROUTINE SETCFL Definition SUBROUTINE SETCFL I CFL INTEGER I CHARACTER CFL Purpose Assigns a value to one of the MERLIN character flags Arguments I input Index of the flag e CFL input Value to be assigned to the I character flag Its effective length should be less than 30 characters otherwise it will be truncated 9 4 11 SUBROUTINE SETCOD Definition SUBROUTINE SETCOD MERR INTEGER MERR 136 MERLIN glue routines Purpose Sets the error code to be returned to the MERLIN operating system upon termination of a plugin module Arguments e MERR input The error code to be returned to the MERLIN operating sy
60. Target value has been reached e 5 The X convergence criterion is satisfied e 6 The simplex has become too small e 7 All variables are fixed e 8 Further progress is not possible Minimization related commands 49 Keyword Description Allowed values NOC Number of calls Any int gt 1 PRINT Printout level 0 1 2 GTOL G convergence criterion 0 lt real lt 1 XTOL X convergence criterion 0 lt real lt 1 FTOL F convergence criterion 0 lt real lt 1 ITER Iterations 1 Inf Any int gt 1 MAD Automatic derivatives On Off USEG Use Recalculate gradient 1 0 USEH Use Recalculate Hessian 1 0 LS Line search conditions Strong Weak LSITER Max LS iterations Any int gt RHO Line search rho 0 lt real SIGMA Line search sigma 0 lt real CANCEL Cancel Proceed 0 1 Figure 6 5 The BFGS panel 6 3 3 BFGS Syntax classification PAC Purpose Invokes the BFGS minimization algorithm using line search and Choleski decomposition for the Hessian The associated panel is listed in figure 6 5 The panel parameters are as follows NOC PRINT GTOL XTOL FTOL ITER An approximate upper bound for the number of calls to the objective function Determines the amount of output from the minimization method Allowed values are e0 No printout at all e 1 Display lower function values as they are discovered e 2 Display function and parameter values as well The gradient termination cr
61. a eee Bids bee wa Ag eo Ae he od 23 did Getting helps al Fee A oR ee 3 ae A pee aoe 24 4 5 Minimizationcommands 0 0 00002 s es s s s s ee 25 4 0 MACTOS GUS Ap a A ie A E ss OE ee E p s 26 4 7 Confidence intervals ee 28 ii Contents 4 8 Command abbreviations e e e e e e e ee 29 4 9 The MERLIN flags and how to use them oana e 29 410 C ll counters ia wk a A Le ee ee RA RE gu Y S 29 AL MERGINGHIES cto atk ods Sek ee hs oe ROE loge X ug O as Bek Bos 30 Curve fitting A complete example 33 Command description 39 6 1 Command classification a a a ea e eee ee a s es sas e 39 6 2 Attribute related commands ee 40 6241 POINT 2 ia 2 bee sd eR GD be s S bp sn S e Q Sus 40 02 27 AIN a A aaa 40 0 2 3 SPACK A a o kus eae ia o AS Ska 41 6 2 4 LMARGIN RMARGEN oi AA al ee a GW 3 42 6 2 5 LDEMARGIN RDEMARGIN 2 0 00 0 2 s s s es eee 42 6 2 66 CELA direct A A ee Petes ek ee Ae ONE A 42 6 256 FEXAEL Q 2 nt eR tee ie So SA Pe Bet BO ee Ye Q ed 43 G28 LOOSE gvn a a ere ef AS Gea eet cee See 43 62229 LOGOS ALL ss a ys sail Bow wh ees a ee ee Sa RR wg oe ee hee 43 6 20 GODEATHER asa Sys e ee Ge ede GUS oe a aici 43 62 11 NONAMES ciales on fenat L See ewe 3 ene S ad Z RUS E e 43 622 12 SHORTDES s f oes e a eae ee e e a tad 44 LANA ES vat yu s m ana aie da eee ae aia eo A Roses any E te near 44 622 04 TERMD ESS Codi Bn th ae hhc a el de dla and
62. alter the MERLIN run time environment For convenience the glue routines are divided in the following four categories e Parameter related Glue routines that set or inquire data structures related to the minimiza tion parameters e Panel related Glue routines that manipulate the panel data structures e Utility Routines that are not specific to MERLIN they are included here however as a pro gramming aid e Miscellaneous The rest of the glue routines that do not fall in one of the above categories In the description that follows subprogram arguments are classified as e Input arguments An initial value must be supplied when the glue routine is called This value remains intact during operation of the routine e Output arguments An initial value need not be supplied when the glue routine is called These arguments will be assigned a value by the glue routine which will be returned to the calling program 115 116 MERLIN glue routines e Input output arguments An initial value must be supplied when the glue routine is called These arguments will be assigned new values by the glue routine which will be returned to the calling program For efficiency reasons there is only a minimal validity check on the arguments Note that REAL variables and arrays should be replaced by DOUBLE PRECISION ones for a double precision instal lation 9 1 Parameter related glue routines 9 1 1 SUBROUTINE GETX Definition SUBROUTINE
63. amed test would be invoked as test When a macro is invoked MERLIN first searches the multi macro file MACROF and then if the macro cannot be found there tests for a file with the same name Macros can contain an arbitrary number of commands and calls to other macros the only restriction being that macro recursion is not allowed Macros can accept optional arguments that are designated as 1 2 etc inside the The default name MACROF can be changed using the MACRO_FILE configuration directive Macros 27 Macro separator S Macro name SHORTDIS 1 5 The first macro starts here STEPDIS 1 5 CLEAR The first macro ends here Macro separator mini Macro name POINT 1 4 The second macro starts here ANAL BFGS NOC 2000 PRINT O VALDIS GNORM CLEAR The second macro ends here Table 4 3 Sample file MACROF with two macros Macro commands Description ECHO The macro name is 0 Display the macro name ECHO You entered arguments How many arguments did the user enter BFGS NOC 1 PRINT 2 Use the arguments in a BFGS call Table 4 4 Sample macro that expects two arguments macro When the macro is invoked they are substituted by the actual arguments supplied by the user The macro name itself is designated as 0 while the number of arguments that are actually entered when the macro is invoked is designated as The sample macro m shown in table 4 4 expects two arguments and can be invoked as m 1000 O
64. amples To assign the name sigma to z and the name rho to x2 use the following GODFATHER 1 sigma 2 rho 6 2 11 NONAME Syntax classification RAC 44 Command description Purpose Clears parameter names Examples To clear the names of z to zs and that of zg use the following NONAME 1 5 8 6 2 12 SHORTDIS Syntax classification RAC Purpose Displays the current values of the minimization parameters and their attributes In addition SHORTDIS displays the title of the run if a title has been set via the TITLE command and the total and partial call counters for the objective function the gradient the Jacobian and the Hessian The value of the objective function is also displayed at the end Issuing simply SHORTDIS is equivalent to SHORTDIS 1 Examples SHORTDIS 3 5 7 displays the attributes of the variables zs through zs and that of z To display the attributes of the fixed variables use SHORTDIS f 6 2 13 VALDIS Syntax classification SIC Purpose Displays title and call counters as the SHORTDIS command and the value of the objective function It does not display the parameter attributes Equivalent to SHORTDIS 1 6 2 14 TERMDIS Syntax classification RAC Purpose Displays the values of the M terms f z in case the objective function has been coded as a sum of squares Examples TERMDIS 1 5 will display the values of the terms fi z through fs z 6 2 15 TITLE Syntax classification UNC Syn
65. an epilog if one exists Examples QUIT 4 STOP NOEPILOG RETURN NOEPILOG QUIT 7 NOEPILOG File manipulation commands 73 Ind Keyword Description Allowed values 1 FILE Memo file name Any string 2 TYPE File type Text Bin 3 OPEN Keep memo file open 0 1 4 CANCEL Cancel Proceed 0 1 Figure 6 16 The MEMO panel 6 8 File manipulation commands 6 8 1 MEMO Syntax classification PAC Purpose Appends a MERLIN record with the values and attributes of the minimization parameters to a specified file The associated panel is listed in figure 6 16 The panel parameters are as follows FILE TYPE OPEN CANCEL The file to write to The file type Allowed values are e TEXT for a MERLIN text file Information is stored in human readable ASCII form Slower but portable e BIN for a MERLIN binary file Information is stored in binary machine dependent form Faster but less portable Specifies whether the MEMO file should remain open after the MEMO command completes Allowed values are e 0 Close the memo file e 1 Leave the memo file open Subsequent MEMO commands will run faster but will be less safe against a system failure This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intende
66. assification UNC Syntax ALIAS alias name command Purpose Renames a command for the current run Examples To create an alias for the command GRADDIS use ALIAS GD GRADDIS 6 6 2 UNALIAS Syntax classification UNC Syntax UNALIAS alias_name Purpose Clears an alias entry Examples To clear the previously defined alias GD for the command GRADDIS use UNALIAS GD 72 Command description 6 6 3 ALIASDIS Syntax classification SIC Purpose Prints out all the aliases and their command equivalences 6 7 Termination and post processing 6 7 1 STOP Syntax classification UNC Syntax STOP NOEPILOG Purpose Terminates the current run by issuing a Fortran STOP statement 6 7 2 RETURN Syntax classification UNC Syntax RETURN NOEPILOG Purpose Returns the control to the calling program i e to the program that calls SUBROUTINE MERLIN It executes a Fortran RETURN statement 6 7 3 QUIT Syntax classification UNC Syntax QUIT integer_flag NOEPILOG Purpose It sets a value to the output flag IQUIT of SUBROUTINE MERLIN and then executes a Fortran RETURN statement The allowed values for the return_flag are positive The RETURN command assigns a zero value to this flag without prompting This flag can be used by the main program as a directive for a required user programmed action referred to as post processing All the above termination commands may take an optional argument that inhibits the execution of
67. ated commands 0 0000 eee r ee r se s 83 6 13 Lo GOVARTANCE 60 stara s o wu imula ere Stan A th a Goon Soak 83 6 13 2 GONETDENCE cocida a IN ST aqu at 84 6 14 Getting help aria ovina geek fea A AE A A A E 84 O 84 AD HELP E A AA A AA A E AS 84 6 14 3 Help on panel keywords e 86 6 15 Odds andeid ste ir A A A oe ae PA a A eS 86 6 R52 SECSHU 2 u a ene ONE aa uq E Se E u a 8 86 OD EPILOG ZE E aa Ac nates A Sepu A A su l 87 6 19 3 CONTROL oi mi 22 20 42 Sed bh A A A Supap klu 87 615 4 HISTORY osa Blk er eee Bo SG Ak Boe ee da a he A Re 89 Extensions 91 GL CWhysextend ts eh a A Bete te Be Ge Ae Se er iy AS al 91 7 2 Writing the plug in module e 91 7 3 Naming the plug in module 0 202 000 2020 s os osos 93 G4 Adding on line help eos aran e A a ae 93 7 5 Plug ins with command line arguments 02 02 0040 94 O Pl g ins withra panel ul ia e A a a AA a eos 94 7 7 The panel description file 0 202000 s os osos 96 7 7 1 Declaring the panel name 2 a r r s sr sr e ee e s es e 96 Contents 7 7 2 Declaring the keywords e 7 7 3 Adding help texts 8 The MERLIN MCL configuration file 8 1 General description 8 2 Directives that control MERLIN input output e 8 2 1 8 2 2 8 2 3 8 2 4 8 2 5 8 2 6 8 2 7 8 2 8 8 2 9 MERLIN input output units and filles IN
68. auo oy 07 uerqovef paje uur3sa T eoTtIatanu y sreduos JUVANDOC S9JUSISHIP premog Bun T OOTISUINU P9YRUITISO SI URTGOoe u YANANE ULIqOILf oy oyeTMoTed OF sn SI TYNVE ANILAOWANS Poriddns ssn aq TWNVE SOATJCALIOP OT OJLTNITeD O p sn SI TYNVUD ANILNOWANS u9 lu J9SN AML TVNV pour JU9ISHIP Y ZUISN p jeurs IQ 0 JUSUOAUIO Ju rpe 38 yL sAo V apow caput QAXIN SOATJLATIOP BY 9JBUITISO 0 POSN ST e Inutroj DIIJQUIUI S ISPIO 19Y3TY V YAWN SOATJLALIOP OT 9JBUITLISO o posn ore s osu s grp PEIFU avab SOATJCALIOP Y 9JLUIT SO OF p sn ore s ou z gip PIBMIOH LSVA SPU NI TH3 A UI pying oy s erdstg SLINIT uomes do Jo sapour yuetino ayy skepdsiq SIGHd0W x f swo py ay jo sanjea oy seldsiq gaput SIAWYAL anjea JUSIIMo Y s ejdsi SICIVA siojyouresed y JO S93NQ11338 pue sonjea yuexmo oy sAvTdsiq gaput SIGLYOHS abv nas Uols SPUDWULOD 1DUOLIDUWLOLU d 99V qu q P puo T poyjJeul TIDY 94 103 sdoys YOrees SP NIJSUOQ TIVda LS poyjJeUl TIDY 94 103 sdoys YOrees SP NIJSUOQ LSA av sdo3s yorees TIOU oy s lt e dsIGT gaput SIddaLS 92U919J9H YON NITUA Y AOTANVd NOTANVd rnd Lau OLS DSd dvud qSVITV n SVITV CDVIAD d9YT4 DVIAD DYTA sjoued po sum sjoued uo sum NITIAN ANTLNOYAINS D I e5 yey wresSo1d oy ol oayuoo sumyoy NITIAN ANTLNOYANS pores yey wresZo1d oy 03 oayuoo sumo y UOTINIIXO SOYRUTUIIO Y ay eyep A X Aue 10 uonounj oy jo y de13 d1199950J Y SIEN uomou
69. aximum number of variables PARAMETER MXV 200 Maximum number of terms PARAMETER MXT 200 The 2 dimensional storage required by some Merlin commands depends on the maximum number of parameters MXV and the maximum number of terms MXT If MXV 11 gt MXT one needs MAX1 storage locations PARAMETER MAX1 MXV 2 11 MXV Otherwise PARAMETER MAX2 MXV MXT For this example we chose MAX1 actually MAX2 would be ok too PARAMETER MAXW MAX1 Alternatively if you don t have that much storage available set MAXW to any positive value Commands that need more storage will not be executed by Merlin DIMENSION VERSIM MAXW WRITE Enter number of variables number of squared terms READ N M CALL MERLIN N M VERSIM MAXW IQUIT END Figure 3 1 A sample main program 13 14 User written programs FUNCTION FUNMIN X N DIMENSION X N X1 X 1 X2 X 2 FUNMIN 10 X2 X1 2 2 1 X1 2 END Figure 3 2 A sample FUNCTION FUNMIN FUNCTION FUNMIN X N DIMENSION X N X input is an array holding the values of the parameters zi N input is the dimensionality of the problem FUNMIN output upon return assumes the value of the objective function f x An example for the Rosenbrock function f x 100 x2 21 1 21 is shown in figure 3 2 3 3 The objective function Sum of squares form This must be written as a subroutine subprogram SUBROUTINE SUBSUM
70. be associated with the integer value It must exist in the panel of the command currently being executed e IVAL input An integer value to be associated with the keyword e TERR output An error code indicating success or failure Possible values are IERR 0 The routine completed successfully IERR 1 The panel description file indicates that the value of IVAL is not allowed for the given keyword 9 2 8 SUBROUTINE SETPR Definition SUBROUTINE SETPR KEY RVAL IERR CHARACTER KEY REAL RVAL INTEGER IERR Purpose Subroutine SETPR assigns the floating point number RVAL to the keyword KEY in the current panel Arguments KEY input The keyword to be associated with the real value It must exist in the panel of the command currently being executed 126 MERLIN glue routines e RVAL input A real value to be associated with the keyword e TERR output An error code indicating success or failure Possible values are IERR 0 The routine completed successfully IERR 1 The panel description file indicates that the value of RVAL is not allowed for the given keyword 9 2 9 SUBROUTINE SETPS Definition SUBROUTINE SETPS KEY SVAL LES IERR CHARACTER KEY SVAL INTEGER LES IERR Purpose Subroutine SETPS assigns the character string SVAL to the keyword KEY in the current panel Arguments e KEY input The keyword to be associated with the string value It must exist in the panel of the
71. bian numerically For the Jacobian forward differences are used The Hessian can always be calculated by using function values However if the user has supplied his own code for the gradient MERLIN can estimate the Hessian using these gradient code The appropriate formulas are given in chapter 6 The minimization commands BFGS DFP and TRUST can take advantage of this capability by using this rather well estimated Hessian initially instead of the unit matrix So one first calculates the Hessian and then instructs one of the above three commands to employ it as an initial approximation This is facilitated by setting the USEH parameter in their panels equal to 1 However since the routines do not use the Hessian directly but its Choleski factors after calculating the Hessian one must decompose it and then proceed with one of the above commands The relevant input to achieve this is listed in table 4 2 4 6 Macros A macro is a collection of MERLIN commands and calls to other macros Macros are identified by a symbolic name and are stored either individually each macro in a separate file or collectively in a special multi macro file named MACROF A macro stored in a separate file is named after the filename Macros stored in file MACROF have their names explicitly declared inside the file along with the constituent commands A sample MACROF is shown in table 4 3 A macro is invoked using its name prepended by a dot For example a macro n
72. calculate on change 1 0 1 4 PRINT MAD printout 0ff 0n 0 0 1 Figure 6 14 The MAD panel 6 5 7 JCOMPARE Syntax classification SIC Purpose Compares the numerically estimated Jacobian to the one calculated by the user supplied code 6 5 8 GNORM Syntax classification SIC Purpose Calculates the L1 L and Lo gradient norms along with the RMS gradient defined as N L X lgi i l N L 5 92 i l L max g 1 2 N 1 N _ 2 9RMS N gt 9 6 5 9 MAD Syntax classification PAC Purpose Sets the thresholds for automatically switching derivative modes from FAST to QUAD and from QUAD to NUMER The associated panel is listed in figure 6 14 The panel parameters are as follows FQ The FAST to QUAD transition threshold When a gradient component that is calculated using mode FAST falls below this value its mode is set to QUAD 68 Command description QN The QUAD to NUMER transition threshold When a gradient component that is calculated using mode QUAD falls below this value its mode is set to NUMER RECALC Determines whether a recalculation of the partial derivative should occur each time a mode transition takes place Allowed values are e 0 Do not recalculate each time a transition occurs el Recalculate using the new derivative mode PRINT Determines whether the user should be notified when a change in the gradient mode occurs Allowed values are e 0 No informative
73. commands 0 r sr rr r er es ee 73 6 80 MEM a a oe hoe envio O a gees 73 0 09 27 DUMP sates a alto 0 Gee ee 4 u a a Shae a eth a See eg 74 6 0 3 DISCARD ee e oki ests O kaca Bide ack oe Bp Ove ale eo ask eh aed 75 6 8 4 DELETES u sys SC Seale ee eee hae PS AG Se Ae eS 75 lv Contents 0807 REWIND 0 a o O e a ee A ee SO asl t 76 6 89 07 GGDEDE gt oct A A a ee a pl 76 O88 JINSPECT ecos kiy s q Sek wR GR Ww a 2 la a fs 76 6 9 Graphics and related commands 0 0 eee eee ee ee es 77 6 91 GRAPH s t soe Sa ek a k GS Heo AAA SG eS W SU amp 77 0 92 PSGRAPH 25 a A RS See ee Goat ak eee Ge ke 78 6 10 Panel related commands 2 0 ee e se s es es e s 81 6101 PANEL ON L dk as bind chk th hes Baia de at tied Gece gk to ad kat ota A be dt 81 6 102 SPANELOFEF lt ys Goel os deri hicks BOR BE hn A ee AE aed US Sa a 81 60S PSTATUS Cu L Moe th aC p aa s Mg AR eM i nee ead as te 81 6510 4 PDUMP soi Rs S Reba Sine Ree Fe a Ee Boe Ee 81 6 11 Output redirection and related commands 05005 82 Oe HIDEOUT lt a eo eee ee BR E eek Ae AAA ee A 82 6 112 REVEAL uk eb wes A eae aha hk bo de Su be te a we es 82 6 12 Macro and MCL related commands a 82 6 12 11 MACRO A xc eo sul we el Pot ee et hel dee GE S S a Be ataw a 82 0 12 CLEAR tia Ba th SN e A qea Pht ee a ee ya aY 83 612 3 RUNMCL 6 2 eng ee A ee E o a ee a 83 6 13 Data fitting rel
74. components are estimated the operation mode that can be set to either error tolerant for interactive use or strict for batch processing etc e Commands that issue information about the current state of both the optimization process and the system For example command SHORTDIS displays the attributes of the current minimization parameters the corresponding value of the objective function and the number of function and gradient calls spent so far Also the command MODEDIS displays the currently set options for the various modes e Commands that perform file manipulation operations For instance the command DELETE that erases a file or the command MEMO that appends the current attributes of the minimization parameters to a file etc e Commands that deal with the construction of macro packages aliasing and other utilities 4 2 Supplying input Most MERLIN commands accept arguments that specify their action Arguments are either manda tory or optional The most general form of a command has the following structure command mandatory arguments optional_arguments Note that a command may or may not have either mandatory or optional arguments One may proceed by entering only the command s name In that case MERLIN will prompt only for the mandatory if any and not for the optional arguments i e in this case the syntax is command cr mandatory_arguments MOS first checks that the entered command is a valid one in which case
75. criterion The search is terminated when the endpoints that bracket the minimum have a relative distance less than LSTOL The standard simplex termination criterion SIMPLEX terminates when the standard deviation of the function values at the vertices is less than FTOL 48 XTOL ITER ALPHA BETA GAMMA CANCEL Command description SIMPLEX terminates when either one of the following conditions hold e The standard deviation of every minimization parameter with respect to all sim plex vertices is less than XTOL The scaled distance between two successive iterates is less than XTOL The number of Simplex iterations to perform A value of 1 allows an unlimited number of iterations The reflection factor The contraction factor The expansion factor This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS ITERDONE INFO Number of function evaluations that were performed Number of Simplex iterations that were performed Result code Possible values are e 1 The specified function accuracy has been achieved e 2 The specified number of iterations has been reached e 3 All function evaluations have been used e 4
76. d 74 Command description Keyword Description Allowed values FILE File to write to Any string WHAT What to write x l r f s n NPL Numbers per line Any int gt APPEND Append to the file Yes No FROM Index to start from Any int gt TO Index to end to Any int gt VALUE Write value Before After Never FORMAT Format eg E20 10 Any string CANCEL Cancel Proceed 0 1 Figure 6 17 The DUMP panel 6 8 2 DUMP Syntax classification PAC Purpose Stores the current values of the minimization parameters or any of their attributes in a file The associated panel is listed in figure 6 17 The panel parameters are as follows FILE The file to write to WHAT Specifies what to write Allowed values are eX Write the current point eL Write the left margins eR Write the right margins e F Write the fix statuses 1 for a free variable 0 for a fixed one eS Write the search steps used by the ROLL command e N Write the symbolic names of the parameters NPL Specifies how many numbers will be written on each line of the file This does not apply to symbolic names which are always written one per line Setting NPL to 0 lets the system decide for the actual numbers per line APPEND In case the specified file exists APPEND determines what to do with its previous contents Allowed values are e NO The previous contents of the file are overwritten e YES The new values are appended at the end of the file FROM S
77. d values are e 0 Do not connect the data points el Connect the data points using straight lines Number of X axis ticks Number of Y axis ticks Specifies the paper size Allowed values are e 0 A4 paper size 8 26 x 11 69 el B5 paper size 7 16 x 10 12 e 2 US Letter paper size 8 5 x 11 e 3 US Legal paper size 8 5 x 14 This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway el is the default value and the process advances normally e 0 cancels the action initially intended Panel related commands 81 6 10 Panel related commands 6 10 1 PANELON Syntax classification UNC Syntax PANELON panel_name panel namez Purpose Activates one or more panels Without any arguments it turns on all MERLIN panels Examples PANELON ROLL BFGS PICK 6 10 2 PANELOFF Syntax classification UNC Syntax PANELOFF panel name panel namez Purpose Deactivates one or more panels Without any arguments it turns off all MERLIN panels Examples PANELOFF BFGS PICK 6 10 3 PSTATUS Syntax classification UNC Syntax PSTATUS panel_name panelnamez Purpose Displays the status of some or all MERLIN panels A panel can be active on or inactive off Without any arguments the status of all MERLIN panels is displayed 6 10 4 PDUMP Syntax classification UNC Syntax
78. d accomplish the same effect These are referred to as the standard input and output unit numbers correspondingly For example READ 5 x WRITE 6 x Some operating systems use unit numbers other than 5 and 6 or allow the user to assign its own unit numbers to the input output devices Some others require a Fortran OPEN statement before the device can be used for input output operations In addition one may want to use regular disk files for input and output instead of the usual devices This section describes the configuration directives that control the way MERLIN handles its input and output 8 2 2 INPUT_FILE Syntax INPUT_FILE filename Directives that control MERLIN input output Configuration directive Default value INPUT_FILE OUTPUT_FILE INPUT_UNIT OUTPUT_UNIT INPUT_PRECONN OUTPUT_PRECONN HEADER PRINTOUT PDESC_FILE MACRO_FILE HELP_FILE MCL_ERROR_F ILE MCL_OBJECT_FILE HAS_APPEND SIZE_REAL SIZE_INT SIZE_CHAR UNIT_RANGE ONEOF FILE MODE PROLOG EPILOG PLUG BIGGER SMALLER MACHINE_DIGITS full PDESC MACROF HELP ERROR The standard output unit 50 80 return Not applicable iaf No prolog is executed No epilog is executed Not applicable 1036 10736 As determined at MERLIN startup Table 8 1 Default values for all configuration directives 103 104 Purpose Default Used by Examples The MERLIN MCL configuration file INPUT_FILE specifies that MERLIN
79. d output device terminal ie a Fortran statement of the form WRITE Cunit_number x should be able to write output to the terminal If this directive is omitted unit_number defaults to 6 This value is suitable for most compilers running under Unix MERLIN only OUTPUT_UNIT 9 8 2 6 INPUT_PRECONN Syntax Purpose Default Used by Examples INPUT_PRECONN preconnect Specifies whether the Fortran input unit as specified by the INPUT_UNIT directive is preconnected to the corresponding input device Preconnected input units need no Fortran OPEN statements before they can be used for input preconnect may be either yes or no If this directive is omitted INPUT_PRECONN yes is assumed MERLIN only INPUT_PRECONN yes 8 2 7 OUTPUT_PRECONN Syntax Purpose Default Used by Examples OUTPUT_PRECONN preconnect Specifies whether the Fortran output unit as specified by the OUTPUT_UNIT directive is preconnected to the corresponding output device Preconnected output units need no Fortran OPEN statements before they can be used for output preconnect may be either yes or no If this directive is omitted OUTPUT_PRECONN yes is assumed MERLIN only OUTPUT_PRECONN yes 106 The MERLIN MCL configuration file 8 2 8 HEADER Syntax Purpose Default Used by Examples HEADER header_status Determines whether the informative messages that are normally printed during MERLIN startup
80. de reasonable defaults any attempt to change them would become quite tedious due to the size and complexity of the source code Instead of hard coding a default value in the source we made use of an installer macro An installer macro is a symbolic name that is referenced in the source as name Therefore the distribution files contain statements like IMPLICIT TYPE A H 0 Z PARAMETER MXV MXV PARAMETER MXT MXT In the above statements the installer macros TYPE MXV and MXT must be substituted with actual values before the programs can be compiled Hence the term installation refers to the production of a valid Fortran source code from the distribution files After installation is complete the above statements might look like IMPLICIT DOUBLE PRECISION A H 0 Z PARAMETER MXV 200 PARAMETER MXT 400 A complete list of all installer macros used in the MERLIN MCL source code is given in 2 2 3 2 2 2 Running the installer program To ease the installation process we have developed a small installer program written in Fortran 77 Its main purpose is to replace all instances of the installer macros in the MERLIN MCL distribution files with actual values and output a valid Fortran source ready for compilation The actual values to be substituted are supplied interactively by the user Note that the source code for both MERLIN and MCL must be processed by the installer Compiling and runn
81. e default value and the process advances normally e 0 cancels the action initially intended 6 2 4 LMARGIN RMARGIN Syntax classification RAVAC Purpose Set the lower and the upper bound correspondingly Examples To restrict zs through xg in 3 5 and zo in 0 oo use the following LMARGIN 5 8 3 10 0 RMARGIN 5 8 5 6 2 5 LDEMARGIN RDEMARGIN Syntax classification RAC Purpose Clear the restrictions of the lower and upper bounds correspondingly Examples To clear the lower bounds of parameters x through zs use LDEMARGIN 1 3 6 2 6 FIX Syntax classification RAC Purpose Fixes specified parameters to their current values Attribute related commands 43 Examples To fix parameters 11 3 6 and 219 use FIX 1 3 6 10 6 2 7 FIXALL Syntax classification SIC Purpose Fixes all parameters to their current values This is used when one wants to let only a few variables free and it seems convenient to fix all variables and then loose a few Equivalent to FIX 1 6 2 8 LOOSE Syntax classification RAC Purpose Frees fixed variables Examples To loose parameters 11 3 6 and x10 use LOOSE 1 3 6 10 6 2 9 LOOSALL Syntax classification SIC Purpose Frees all variables Equivalent to LOOSE 1 6 2 10 GODFATHER Syntax classification RAVAC Purpose Assigns symbolic names to the minimization parameters Each name must be up to 10 characters long and is case insensitive Ex
82. e iterations is less than XTOL Termination criterion based on function values The method terminates when the rela tive function drop in two successive iterations is less than FTOL An estimation of the relative error in the calculation of the objective function This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway el is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs Minimization related commands 59 Keyword Description Value Allowed values NOC Number of calls 10000 Any int gt 1 TARGET Target value 1 E 300 Any real MAD Automatic derivatives Off On Off CANCEL Cancel Proceed 1 0 1 Figure 6 11 The AUTO panel FCALLS Number of function evaluations that were performed JCALLS Number of evaluations of the Jacobian matrix ITERDONE Number of LEVE iterations that were performed INFO Result code Possible values are e 0 Some input parameters were incorrect e 1 The function value has converged e2 The X convergence criterion is satisfied e 3 F and X convergence has been achieved e4 The gradient criterion is satisfied e 5 All function evaluations have been used e 6 Further progress is not possible e 7 Further progress is not possible e 8 Further progress is not possible e 9 Target
83. e of file abc Allowed values are e 0 Do not check for macros on disk files e 1 Check for macros on disk files ECHOMAC This setting affects the printing of informative messages indicating that a macro has started stopped executing Allowed values are 88 ECHOPRO MCLKEYS ECHOCOM KEEPIN KEEPOUT MCLBUF Command description e 0 Do not issue informative messages el Issue informative messages Determines whether informative messages are printed each time the MERLIN prolog epilog begins or ends execution Allowed values are e 0 Do not issue informative messages e 1 Issue informative messages Specifies whether the MCL specific keywords and their values that are normally returned to an MCL program should be printed after a panel command terminates MCL specific keywords are identified in the panel description file by the trailing question mark eg INFO Allowed values are e 0 Do not print the MCL specific keywords e 1 Print the MCL specific keywords Controls printing of the current command before executing it Allowed values are e 0 Do not print the name of current command el Print the name of current command Controls the handling of the MERLIN input file when MERLIN execution ends Allowed values are e 0 Delete the MERLIN input file when MERLIN execution ends e 1 Do not delete the MERLIN input file when MERLIN execution ends This setting only applies when the configuration direct
84. e steepest descent direction every N iterations Specifies whether the MERLIN Automatic Derivatives are to be used when approximating the gradient vector Allowed values are e ON The MERLIN Automatic Derivatives are to be used Minimization related commands 57 USEG LSITER RHO SIGMA CANCEL e OFF Use the current derivative mode Determines how to obtain the gradient vector for the initial current point Allowed values are e0 Do not use the values in the gradient cache Recalculate the whole gradient vector e 1 Instead of recalculating the gradient vector use the values in the gradient cache The maximum number of iterations that are allowed in the line search The p parameter used in the termination criteria for the line search The o parameter used in the termination criteria for the line search This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS Number of function evaluations that were performed GCALLS Number of evaluations of the gradient vector ITERDONE Number of conjugate gradient iterations that were performed INFO Result code Possible values are e 1 Target value has been reached e2 The gradient crite
85. e the backup records to the file CANCEL This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended 6 5 13 NOPRINT HALFPRINT FULLPRINT Syntax classification SIC Purpose Set the printout mode FULLPRINT allows the full output to be displayed HALFPRINT allows only warnings and error messages NOPRINT suppresses all output 6 5 14 GENERAL SOS Syntax classification SIC Purpose Determine which form for the objective function is to be used GENERAL Makes calls the FUNCTION FUNMIN SOS Makes calls to SUBROUTINE SUBSUM The default setting depends on the number of terms M supplied when SUBROUTINE MERLIN is called When M 0 the default is set to GENERAL SOS otherwise Aliasing and related commands 71 6 5 15 EVALUATE NOEVAL Syntax classification SIC Purpose NOEVAL disallows evaluation of the objective function EVALUATE allows the evaluation of the objective function if it was disallowed and in addition forces one evaluation 6 5 16 MODEDIS Syntax classification SIC Purpose Displays the current operation modes 6 5 17 LIMITS Syntax classification SIC Purpose Displays the values of several installation parameters 6 6 Aliasing and related commands 6 6 1 ALIAS Syntax cl
86. ecified by the user at run time or set by the MERLIN Operating System to indicate an error condition Possible values are A RETURN command was issued by the user A QUIT command was issued with the specified value for IQUIT There is not enough one dimensional storage for this problem You must redimension by running the installer and recompile MERLIN MERLIN cannot allocate the initial unit numbers for the configura tion file The output file or unit cannot be opened Moreover some errors occurred while parsing the configuration file An error occurred while parsing the configuration file The error is related to directives that set the output unit or file The output file or unit cannot be opened The configuration file has been successfully parsed An error occurred while parsing the configuration file The error is not related to the output file or unit which has been successfully opened An error occurred while parsing the panel description file The input unit cannot be opened An End of File condition was encountered in the input file or unit A run time error other than End of File has occurred incorrect command MCL runtime error etc This value will be returned only if the BATCH mode was set A sample main program is listed in figure 3 1 3 2 The objective function General form This must be written as a function subprogram The objective function General form PROGRAM MASTER M
87. eir panel standing for MERLIN Automatic Derivatives This op tion when it is turned on allows according to some criterion the automatic transition from a lower to a higher accuracy mode This is done separately for each component of the gradient This means that at a particular instant some components will be calculated in the FAST mode some others in the QUAD mode etc This is designed so as to economize calls to the objective function The criterion for a transition is based on the absolute value of the gradient component Two numbers thresholds are specified one for the transition from FAST to QUAD and another for the transition from QUAD to NUMER A derivative changes from FAST to QUAD if its absolute value is below the first threshold Similarly the second threshold arranges for the QUAD to NUMER transition The rational behind this criteria is that as the minimum is approached the gradient components tend to become smaller and smaller in absolute value The closer to the minimum the more accurate estimation of 26 The MERLIN Operating System HESSIAN DO C Calculate the Hessian HESSIAN DO D Decompose the Hessian to its Choleski factors BFGS NOC 1000 USEH 1 Instruct BFGS it to use the existing Choleski factors Table 4 2 Using an initial Hessian approximation the gradient is needed The thresholds can be set via the MAD command and their values depend on the problem at hand MERLIN can also estimate the Hessian and the Jaco
88. er 1 Introduction 1 1 What kind of problems MERLIN handles Multidimensional minimization is a common procedure needed in many fields A variety of problems in engineering physics chemistry etc are frequently reduced to ones of minimizing a function of many variables For instance we refer to systems of non linear equations to variational methods to curve fitting and to the training of neural networks Minimizing a multidimensional function faces a lot of difficulties There is no single method that can tackle all problems in a satisfactory way It has been realized that one needs a strategy combining different methods to efficiently handle a wide spectrum of problems The presence of constraints even of simple ones enhances the difficulty Many algorithms require evaluation of the gradient This imposes additional problems since it is not always straightforward to code it Hence one resorts to approximating the derivatives using differencing that costs in computing time as well as in accuracy MERLIN is an integrated environment designed to solve optimization problems It is devised to be easy to use and implemented so as to be portable among different platforms Another feature is that MERLIN is open i e a plug in mechanism is provided so that others can easily embed their own code modules MERLIN handles the following category of problems Find a local minimum of the function fla ER w 21 20 2N under the condit
89. ered IY SJ SIY LASHY UOISSOS NITHUAJN JUOIINO IY 107 91919 JOYS Y SI9G uowssas S14 sof IML TILIL aU NITYA Y WOI pI0991 Y SADA puvwwos jpouvd Y9Id ay Y WO S9INQLIYYE 1U 10 SON LA Joyouresed oy Speoy puvwwos 9uod LINI siojourered y VOI s urgu OTJOQUI S oY SIAQUISH 7 gaput HNVNON S19J9uIe ed ay 09 soweu ITOQUI S SUBISS Y 9UDU TIPUL YAHLVACOD s19J9uIeIed Jre s soo TIVSOOT S19J9UIe1ed Jre SOXIH TIVXIA SI9J9UIRIVd ay JO SUIOS SISOO Laput ASOOT Sonyea JUSIMO rqu 0 ssojyourered ay JO SOS SOXTH gaput XIA s19j9ue1ed y wog spunog 1eddn y s xour t t Caput NIDUVWACY siojowered oy WOI SPUNOQ JaMOT IY SOAOWIOY 7 gaput NIDUVWACT siojourered oy uo spunoq I ddn sy9g INDA TIPUL NIDUVIY siojyowered y UO spunoq IMO 398 anjona Lapul NIDAVWT siojourered ay 0 sones susIssy INDA LIPUL LNTOd 92U949J9H MOMO NITUAIN wistueyou ANA NITYANW 94 S9IN YUOL puvwwo jaund anova sp10931 dnypeq d y you s o T MOVAON p 10991 dnypeq juaded 3sour ay sdeoy MOVALSVT sp1o0991 dnypeq pre sdeay MOvaTINA uoryetedo yoyeq s359 9S HOLVd uUOrye lado BATJOVIOJUI SPAS Avi SOATICATLIO ITJVWIOINY NITHYA OY Sounsyuoy pupunuoo2 jauod OYN XIIJEUL URISSOH ot 07 payejol suoneiodo puvwuwos jauvd NVISSHH SULIOU JUSTPeI3 oy skepdsiq WYOND JUSTpe 13 oy SUTYeTNoTed JO s pour JUSISHIP om s reduroo gapur Zapou Tapow yOaHOaVYD syu uoduioo Juerpel3 ayy skeTdsiq aput Staqvup ay Aq porjddns
90. ertainties in the fitted parameters z are inside a region in which the model could be replaced by a suitable linearized model Let v be the number of parameters whose joint confidence region we wish to compute and p the desired confidence limit The covariance matrix C is defined as C 2 G The procedure involves two steps Initially using the COVARIANCE command one must set the desired confidence limit p and calcu late the covariance matrix of the fit MERLIN calculates the second derivative matrix using finite differences inverts it using Choleski decomposition writes the resulting covariance matrix to a file for further work and prints the standard errors c y G Once the covariance matrix is calculated and stored one must invoke the command CONFIDENCE with appropriate arguments to calculate the joint confidence region for any number v of param eters For example to calculate the confidence region for parameters 2 and 5 use the command CONFIDENCE 2 5 MERLIN reads the stored covariance matrix and forms a new v x v matrix C using the intersections of the y rows and columns of C corresponding to the parameters specified in the CONFIDENCE command Using a simple bisection routine it solves the equation Q v 2 4 2 1 p 4 2 for A and prints out the standard errors oc Cj and the corresponding confidence intervals 6x VA oj Q v 2 A 2 is the incomplete Gamma function and A is a value such that the Command abbreviat
91. gure 6 18 The panel parameters are as follows FILE The file to inspect Graphics and related commands 77 TYPE DIR PRINT FROM TO CANCEL The file type Allowed values are e TEXT for a MERLIN text file Information is stored in human readable ASCII form Slower but portable e BIN for a MERLIN binary file Information is stored in binary machine dependent form Faster but less portable Determines the direction of the inspection Allowed values are el The file is inspected forwards from the beginning to the end e 1 The file is inspected backwards from the end to the beginning The settings of FROM TO also affect the direction of inspection For a forward inspection FROM should be less or equal to TO while for a backward inspection FROM should be greater than or equal to TO If these conditions do not hold the selected direction is automatically inverted Determines the amount of output during file inspection Allowed values are e0 No printout at all e 1 Display function values e 2 Display function and parameter values as well The record where inspection starts The record where inspection ends This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway el is the default value and the process advances normally e 0 cancels the action initially intended The following paramete
92. har acter strings enclosed in quotes according to the corresponding keyword type In the case of keywords of type C or S the special entry any will cause any value to be accepted Examples 1 2 3 any a b c on off default_value The default value for the keyword It should be one of the allowed values short_description A short description of the keyword that will appear in the panel It must be enclosed in a pair of single quotes Examples NOC I 1 inf 300 Number of calls PRINT I 0 1 2 1 gt Printout level FILE S any HESSIAN File to write to WHAT C F D F What to plot Fun Data INFO I 0 inf 0 Result code 7 7 3 Adding help texts An explanatory help text for the command itself and for each of the keywords can be included in the panel description file The help text for the command itself is displayed using the MERLIN HELP command HELP command The help text for a specific keyword is displayed using a question mark after its name command keyword Help texts for all panel commands as well for all of their keywords is included in the distributed panel description file Note that the help texts for all non panel commands reside in the MERLIN help file The help texts in the panel description file have the form help keyword help_text end keyword The name of a keyword which if present associates the help text with the keyword If keyword
93. he user can call from his code and then decide what to do according to the flag s value This is very convenient if for example at some stage one decides that wants to print the values of some variables or arrays used in his program Also a flag can be used to implement a penalty factor in order to solve a constrained optimization problem This version of MOS supports twenty numerical and ten character flags each one being 30 characters long An example is listed in figure 4 2 4 10 Call counters MERLIN has eight counters Their current values appear in the output produced by the commands SHORTDIS and VALDIS The four of them count the calls to 1 The objective function FUNCTION FUNMIN or SUBROUTINE SUBSUM 30 The MERLIN Operating System FUNCTION FUNMIN X N DIMENSION X N C Call the glue routine that will return C the current value of the 1 flag CALL GETFLA 1 FLAG expression another_expression FUNMIN A 2 Bx x 2 C Print the values of A and B C if the user has set the 1 flag to three IF NINT FLAG EQ 3 WRITE A B END Figure 4 2 Usage of the MERLIN flags 2 The user supplied code for the gradient SUBROUTINE GRANAL 3 The user supplied code for the Jacobian SUBROUTINE JANAL 4 The user supplied code for the Hessian SUBROUTINE HANAL Counting starts at the beginning of the run and these counters cannot be reset total counters The remaining four counters called partial counters
94. imization param eters 6 8 4 DELETE Syntax classification UNC Syntax DELETE filename filename Purpose Deletes one or more files Examples DELETE DATAFILE store deletes the files DATAFILE and store 76 Ind Keyword 1 FILE 2 TYPE 3 DIR 4 PRINT 5 FROM 6 TO 7 CANCEL 6 8 5 REWIND Description Value File name to inspect BACKUP File type Text Direction Forw Backw 1 Print Nothing Value Point Record to start from Record to end to Cancel Proceed Figure 6 18 The INSPECT panel Syntax classification UNC Syntax REWIND filename file names Purpose Rewinds one or more files Mainly used in MCL programs Examples REWIND DATAFILE store rewinds the files DATAFILE and store 6 8 6 GOEOF Syntax classification UNC Syntax GOEOF file_name file names Command description Allowed values Any string Text Bin 1 1 0 1 2 Any int gt Any int gt 10 1 Purpose Positions one or more files to the end of information Mainly used in MCL programs Examples GOEOF DATAFILE store positions the files DATAFILE and store to the end of information 6 8 7 INSPECT Syntax classification PAC Purpose Displays the contents of a file containing MERLIN records stored by the backup mech anism or the MEMO command Inspection can proceed forwards or backwards and can display parameter values or function values only The associated panel is listed in fi
95. in modules If an error occurs while reading the configuration file MCL will print appropriate messages and abort execution MERLIN will return control to the calling program indicating the problem through the return flag IQUIT Possible values are IQUIT 3 Some errors occurred while parsing the configuration file Moreover the MERLIN output file could not be opened IQUIT 4 Some error occurred while parsing the configuration file The error is related to the 101 102 The MERLIN MCL configuration file directives QUTPUT_FILE OUTPUT_UNIT or OUTPUT_PRECONN that control the output file IQUIT 5 The configuration file has been successfully parsed The output file could not be opened however IQUIT 6 Some error occurred while parsing the configuration file The error is not related to the directives QUTPUT_FILE OUTPUT_UNIT or OUTPUT_PRECONN that control the output file Table 8 1 summarizes the defaults for all configuration directives in case some of them are omitted or a configuration file is not used 8 2 Directives that control MERLIN input output 8 2 1 MERLIN input output units and files Usually a Fortran statement of the form READ x x expects its input from the keyboard Likewise the statement WRITE x displays its output to the screen of a terminal Fortran compilers have a pair of unit numbers for example 5 and 6 that refer to the keyboard and terminal screen correspondingly an
96. ing the installer program is straightforward For example on a Unix system 77 0 o install install f install Installation 7 TYPE DOUBLE PRECISION MXV 200 MXT 200 CONFIG CONFIG FC 33 MCLMEM 50000 MCLBUF 50000 MXPLUG 50 Figure 2 1 Sample installer definitions file Installation is then carried out in three steps 1 The installer will interactively ask you for the values of the most important installer macros Then it will record these values in the installer definitions file with the default name DEFS and use them in the next step The format of the installer definitions file is simple each line contains the name of an installer macro and the actual value to be substituted in the source code Blank lines and lines starting with the character comments are ignored Items containing space or tab characters must be enclosed in a pair of quotes A single quote is produced by the sequence A sample definitions file is shown in figure 1 The installer will allow you to prepare a definitions file yourself instead of creating one interactively In this case you must include in the installer definitions file a value for all installer macros listed in 2 2 3 2 The installer will read the installer definitions file either the one created by the installer itself or the one prepared by the user and ask the names of the distribution files Then it will read the contents of the distribution files substitute
97. ion SUBROUTINE SUBSUM 9 4 19 SUBROUTINE GETTRG Definition SUBROUTINE GETTRG TRG ISTARG REAL TRG INTEGER ISTARG Purpose Returns the current target value as defined with a TARGET command A common use of target values is as a termination criterion in a minimization routine The target value can be set with the TARGET command and cleared with NOTARGET Arguments e TRG output The current target value If there is no current target value ISTARG 0 the value returned depends on the current function mode TRG A large negative number When MERLIN operates on a general function TRG 0 When MERLIN operates on sum of squares function e ISTARG output Indicates whether a target value has been set Possible values are ISTARG 0 There is no target value currently in effect 140 MERLIN glue routines ISTARG 1 A target value is in effect and is returned in variable TRG 9 4 20 SUBROUTINE SETADE Definition Purpose Arguments Example SUBROUTINE SETADE IAUTO INTEGER IAUTO Enables or disables the MERLIN automatic derivatives A common use would be to enable the MERLIN automatic derivatives before calling a minimization routine that uses the gradient and disable them immediately after Note that while automatic derivatives are in effect their options are taken from the MAD panel Most of the MERLIN minimization commands have panel keywords that control the use of auto matic deriva
98. ions zi l u for 1 2 N Special merit has been taken for problems where the objective function can be written as sum of squares i e M f z 2 i l 1 2 Introduction This form is particularly suited when one needs to fit data points using a model function One then minimizes the chisquare which is of the above form In this case MERLIN can calculate parabolic estimates of the confidence intervals for the model parameters as well as partial covariance matrices MERLIN can be used both interactively and in batch Interactively the user drives MERLIN by entering commands through the keyboard In batch MERLIN reads commands from an input com mand file Interactively MERLIN is tolerant to errors in input and issues appropriate warning messages while in batch aborts There are various commands at the user s disposal that either invoke minimization algorithms or perform other auxiliary operations MERLIN is programmable Its programming language MCL Merlin Control Language is a high level easy to learn language The McL compiler takes as input a strategy coded in MCL and produces as output a file that contains commands that can steer MERLIN appropriately MERLIN and MCL are both written in ANSI Fortran 77 to guarantee portability 1 2 Conventions 1 2 1 Typing e Lower case boldface letters a g etc stand for vectors in the N dimensional space Upper case boldface letters G H etc stand for N x
99. ions 29 probability of a chisquare variable with y degrees of freedom being less than A is p Finally MERLIN inverts C and prints the equation of the ellipsoid that defines the confidence region A z 2 C x z 4 3 where x is the current minimizer of the objective function The stored covariance matrix can be used by successive CONFIDENCE commands in order to calculate the confidence regions for any combinations of the parameters 4 8 Command abbreviations MOS supports command abbreviations One needs to enter only an initial part of the command name that however identifies it uniquely For example SH is long enough for SHORTDIS PO for POINT BF for BFGS etc However STE is a common part of the three commands STEP STEPALL STEPDIS and hence unique identification is impossible In such a case MOS lists all matching commands to remind the user of the several possibilities Note also that commands can be entered invariably in either lower or upper case 4 9 The MERLIN flags and how to use them MERLIN maintains two arrays for flags One is of floating point type while the other is of character type At run time the user may specify values for these flags The default initial values are zeros for the numerical flags and blanks for the character ones Flags can be used to further extend the control of the MOS inside the user s program There is a glue routine called SUBROUTINE GETFLA see chapter 9 on glue routines that t
100. istory mechanism Allowed values are e ON The history mechanism is turned on e OFF The history mechanism is turned off Specifies what happens if the history mechanism is turned on and the history file exists already Allowed values are e A Append to the already existing file eD Overwrite the previous contents of the history file This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended 90 Command description Chapter 7 Extensions 7 1 Why extend After working with MERLIN for a while one realizes the need for incorporating his own code fragments into MERLIN For example one may want to write to a file the resulting minimization parameters using a strange format produce a graph for a plotter or even add his own minimization routine The possibilities are infinite We decided to incorporate a mechanism for uniformly extending MERLIN without having to modify the body of the program Any extensions added are automatically recognized by MCL programs as well The procedure involves three steps e The user has to provide a subroutine that performs the desired operations A user subroutine that is used as a MERLIN extension is termed a plug in module e A unique name must be chosen for the plug in Thi
101. iterion The method terminates when the relative gradient falls below this value Termination criterion based on the values of the parameters The method terminates when the relative change in the parameters in two successive iterations is less than XTOL Termination criterion based on function values The method terminates when the rela tive function drop in two successive iterations is less than FTOL The number of BFGS iterations to perform A value of 1 allows an unlimited number of iterations 50 MAD USEG USEH LS LSITER RHO SIGMA CANCEL Command description Specifies whether the MERLIN Automatic Derivatives are to be used when approximating the gradient vector Allowed values are e ON The MERLIN Automatic Derivatives are to be used e OFF Use the current derivative mode Determines how to obtain the gradient vector for the initial current point Allowed values are e0 Do not use the values in the gradient cache Recalculate the whole gradient vector e 1 Instead of recalculating the gradient vector use the values in the gradient cache Determines the initial approximation to the Hessian matrix Allowed values are e 0 The initial approximation is set to be the unit matrix e 1 The approximation from a previous BFGS DFP TRUST or HESSIAN command is used Specifies the conditions that terminate the line search Allowed values are e STRONG The strong Wolfe Powell conditions are used
102. ive INPUT_FILE has been used Controls the handling of the MERLIN output file when MERLIN execution ends Allowed values are e 0 Delete the MERLIN output file when MERLIN execution ends e 1 Do not delete the MERLIN output file when MERLIN execution ends This setting only applies when the configuration directive OUTPUT_FILE has been used Determines whether an MCL program should run in buffered or unbuffered mode While in buffered mode MERLIN will attempt to read in all of the object file specified in the RUNMCL command and keep it in memory If the program is too large to fit in the buffer MERLIN reverts to the unbuffered mode In the later case the RUNMCL command will inform the user Allowed values are e 0 Run MCL programs unbuffered el Use the buffer Odds and ends 89 Ind Keyword Description Value Allowed values 1 FILE History file name HISTORY Any string 2 STATUS History status Off On Off 3 OLD Old file Append Delete A A D 4 CANCEL Cancel Proceed 1 0 1 Figure 6 26 The HISTORY panel 6 15 4 HISTORY Syntax classification PAC Purpose Controls the MERLIN history mechanism When history is active all MERLIN commands are stored in a file The file can be used as a macro to repeat a sequence of commands The associated panel is listed in figure 6 26 The panel parameters are as follows FILE STATUS OLD CANCEL The file to store the MERLIN commands Determines the status of the h
103. keyword to be associated with the real value e RVAL input A real value to be associated with the keyword e IERR output An error code indicating success or failure Possible values are IERR 0 The routine completed successfully IERR 1 The panel description file indicates that the value of RVAL is not allowed for the given keyword 128 MERLIN glue routines 9 2 12 SUBROUTINE SETPPS Definition SUBROUTINE SETPPS PANEL KEY SVAL LES IERR CHARACTER PANEL KEY SVAL INTEGER LES IERR Purpose Subroutine SETPPS assigns the character string SVAL to the keyword KEY in the panel specified by PANEL Arguments e PANEL input Name of the panel that contains the specified keyword e KEY input The keyword to be associated with the string value e SVAL input An integer value to be associated with the keyword e LES input Effective length of SVAL e IERR output An error code indicating success or failure Possible values are IERR 0 The routine completed successfully IERR 1 The panel description file indicates that the value of SVAL is not allowed for the given keyword 9 2 13 SUBROUTINE CHANGE Definition SUBROUTINE CHANGE ICODE INTEGER ICODE Purpose This routine interacts with the user and handles panel I O for all panel commands It presents the panel accepts any user changes to the panel parameters and stores the new values in the appropriate data structures Command line arguments are
104. l prompts the user to change the current values supplying an one line input of the form 22 The MERLIN Operating System FIX Fixed variables LOOSE LEFT Variables with left margin RIGHT MARGIN Variables with both margins FAST Variables whose derivative mode is set to FAST QUAD Variables whose derivative mode is set to QUAD NUMER Variables whose derivative mode is set to NUMER ANAL Variables whose derivative mode is set to ANAL NAMED Loose variables Variables with right margin Named variables Table 4 1 Shared parameter properties used in index specifications Keyword NOC PRINT GTOL XTOL FTOL ITER MAD USEG USEH 10 LS 11 LSITER 12 RHO 13 SIGMA 14 CANCEL Enter changes Allowed values Number of calls Any int gt 1 Printout level 0 1 2 G convergence criterion 0 lt real lt 1 X convergence criterion 0 lt real lt 1 F convergence criterion t 0 lt real lt 1 Iterations 1 Inf Description Any int gt 1 Automatic derivatives Use Recalculate gradient Use Recalculate Hessian Line search conditions Max LS iterations Line search rho Line search sigma Cancel Proceed Figure 4 1 Typical MERLIN panel on off 1 0 1 0 Strong Weak Any int gt 1 real lt real lt Output handling 23 parameter value parameter values parameter value Parameters are of course specific to the command being used and may be entered u
105. l value that corresponds to the keyword 9 2 3 SUBROUTINE GETPS Definition SUBROUTINE GETPS KEY SVAL LES CHARACTER KEY SVAL INTEGER LES Purpose Subroutine GETPS returns the character string SVAL assigned to the keyword KEY in the current panel Arguments e KEY input The keyword to search for It must exist in the panel of the current command and have a string or character type otherwise this routine will abort e SVAL output The character that corresponds to the keyword The length of SVAL should should be sufficient in order to accommodate all possible strings as defined in the corresponding panel description file entry If the declared length of SVAL is less then needed the returned string will be truncated to fit without any notification however e LES output The effective length of SVAL 9 2 4 SUBROUTINE GETPPI Definition SUBROUTINE GETPPI PANEL KEY IVAL CHARACTER PANEL KEY INTEGER IVAL Purpose Subroutine GETPPI returns the integer value IVAL assigned to the keyword KEY in the panel specified by PANEL Arguments e PANEL input The panel to be searched It must be a valid panel defined in the panel descrip tion file 124 MERLIN glue routines e KEY input The keyword to search for It must exist in the panel and have an integer type otherwise this routine will abort e IVAL output The integer value that corresponds to the keyword 9 2 5 SUBROUTINE GETPPR Definition
106. lassification RAVAC Modes of operation and related commands 63 Purpose Assigns values to the numeric MERLIN flags The default value for these flags is zero 6 4 2 FLAGDIS Syntax classification RAC Purpose Displays the values of the specified numerical MERLIN flags Without arguments the values of all MERLIN numerical flags are displayed 6 4 3 CFLAG Syntax classification RAVAC Purpose Assigns values to the MERLIN character flags The default value for these flags is a blank character 6 4 4 CFLAGDIS Syntax classification RAC Purpose Displays the values of the specified MERLIN character flags Without arguments the values of all MERLIN character flags are displayed 6 5 Modes of operation and related commands 6 5 1 FAST QUAD NUMER ANAL Syntax classification SIC Purpose Set the way the gradient vector is calculated FAST Forward differences are used to estimate the derivatives This costs one function evaluation per gradient component df f c h f x _ Sy ith h ax 1 em n w vn max 1 x QUAD Central differences are used to estimate the derivatives This costs two function evaluations per gradient component df _ fo h f 0 h a oF with h Y nymax 1 x 64 Command description NUMER A high order symmetric formula is used to estimate the derivatives This costs at least six function evaluations per gradient component df 64f e h f e h _ 20 f z 2h f x 2h 1 f x 4h
107. le commands SIC These commands need no arguments They are called by issuing their names Example RESET 2 Range commands RAC These commands need only range specification arguments Range specifications are described in 84 2 Syntax command_name range ranges Example FIX 1 3 7 8 10 3 Range value commands RAVAC These commands need both range and value arguments Syntax command_name range value range values Example POINT 1 5 10 6 11 2 7 10 3 1 4 Panel commands PAC These commands need arguments as determined by the associated panel Syntax command_name key value key2 values Example ROLL NOC 1000 FAIL 8 39 40 Command description Ind Keyword Description Allowed values 1 FILE File to read from Any string 2 WHAT What to initialize x l r f s n 3 NPL Numbers per line Any int gt 0 4 SKIP Lines to skip Any int gt 0 5 FROM Index to start from Any int gt 1 6 TO Index to end to Any int gt 1 7 FORMAT Format eg E20 10 Any string 8 CANCEL Cancel Proceed 0 1 Figure 6 1 The INIT panel 5 Unclassified commands UNC There are a few commands that do not conform to the above types and do not deserve a separate classification 6 2 Attribute related commands 6 2 1 POINT Syntax classification RAVAC Purpose Assigns values to minimization parameters Examples POINT 1 5 3 1 6 7 8 1 2 Assigns to variables z through zs the value 3 1 to variable rg the value 7 and t
108. le should then be invoked with exactly one argument the file name FILEDIS some _file 7 6 Plug ins with a panel Plug in modules can use the panel mechanism to obtain input and to communicate values to MCL programs Figure 7 6 presents a trivial example of a plug in module that writes some of Plug ins with a panel 95 SUBROUTINE FILESH CHARACTER 10 NI CHARACTER 80 FNAME CALL GETIOUCIUINP IUOUT Find out the output unit number IUOUT CALL ARGNO NARG Find out number of arguments NARG IF NARG NE 1 THEN If incorrect number of arguments WRITE IUOUT One arg please CALL SETCOD 2 Indicate an error RETURN END IF CALL GETARG 1 FNAME LENF Get the first argument NU NUNIT Request a free unit number OPEN NU FILE FNAME Open the file CALL GETDIM N M Find out the number of parameters N DO 10 I 1 N Loop over all parameters CALL GETX1 1 XI Get the value of the Ith parameter XI CALL GETNM1 1 NI Get the name of the I parameter NI CALL GETG1 1 G1 Get the Ith component of the gradient GI WRITE NU 20 I NI XI GI Print them all out CONTINUE CLOSE NU Close the file CALL SETCOD 0 Indicate no error FORMAT 2X 15 2X A 2 2X 1PE14 7 END Figure 7 5 Sample plug in module that takes advantage of command line arguments It uses the glue routines GETIOU ARGNO SETCOD GETARG NUNIT GETDIM GETX1 GETNM1 and GETG1 96 Extensions the minimization parameters to a file In addition it can return to a
109. luations have been used e 2 Further progress is not possible e 3 Target value has been reached 6 3 10 ACCUM Syntax classification PAC Purpose Picks points at random and stores them in a file if the corresponding function value is lower than a preset number The associated panel is listed in figure 6 12 Restriction All free variables must be bounded from both above and below The panel parameters are as follows NOC An upper bound to the number of calls to the objective function Minimization related commands 61 NOP The number of points to accumulate TARGET Sets the target value The points z for which f a lt TARGET are stored in the file specified by the FILE keyword FILE The file to store the accumulated points TYPE The file type Allowed values are e TEXT for a MERLIN text file Information is stored in human readable ASCII form Slower but portable e BIN for a MERLIN binary file Information is stored in binary machine dependent form Faster but less portable CANCEL This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS Number of function evaluations that were performed POINTS Number of points that have been
110. matted file n is used to calculate the appropriate RECL specifier when opening a MERLIN binary file OPEN UNIT unitnumber FILE file name RECL record_length If this directive is omitted SIZE_INTEGER defaults to 4 MERLIN only SIZE_INTEGER 2 8 3 9 SIZE_CHAR Syntax Purpose Default Used by Examples SIZE_CHAR n Specifies that a CHARACTER 1 Fortran variable occupies n storage locations in an un formatted file n is used to calculate the appropriate RECL specifier when opening a MERLIN binary file OPEN UNIT unit_number FILE file_name RECL record_length If this directive is omitted SIZE_CHAR defaults to 1 MERLIN only SIZE_CHAR 1 8 3 10 UNIT_RANGE Syntax UNIT_RANGE from to 110 The MERLIN MCL configuration file Purpose Defines an allowed range of Fortran unit numbers to be used by MERLIN The purpose of the unit range is to prevent MERLIN from interfering with files already open at the timeSUBROUTINE MERLIN is called or with files used within the user written modules FUNMIN GRANAL etc Default If this directive is omitted it defaults to UNIT_RANGE 50 80 Used by MERLIN only Examples UNIT_RANGE 25 40 8 3 11 ONEOF Syntax ONEOF action Purpose Determines the action MERLIN should take when an end of file condition occurs in the input file The specified action is taken only when MERLIN is running in interactive mode When in batch mode MERLIN always returns to the calling program
111. messages e 1 Display an informative message each time a gradient mode changes This can be annoying especially for an objective function with a large number of parameters 6 5 10 IAF BATCH Syntax classification SIC Purpose IAF sets an error tolerant mode suitable for interactive work BATCH sets the strict mode that causes MERLIN to abort on errors and is suitable for unattended batch processing 6 5 11 NOBACK LASTBACK FULLBACK Syntax classification SIC Purpose Set the backup mode NOBACK keeps no backup records LASTBACK keeps only the most recent record FULLBACK keeps a history of all records resulting after the completion of the issued minimization commands A backup record contains the values of the attributes of the minimization parameters Modes of operation and related commands 69 Keyword Description Value Allowed values FILE Backup file name BACKUP Any string TYPE File type Text Text Bin MODE Backup mode No Full Last No WHEN When to Backup MXDL mxd Any string SAFE Safe but slow backup No Yes No CANCEL Cancel Proceed 1 0 1 Figure 6 15 The BACKUP panel 6 5 12 BACKUP Syntax classification PAC Purpose Controls the MERLIN backup mechanism Prevents loss of data from abnormal program termination The associated panel is listed in figure 6 15 The panel parameters are as follows FILE The backup file name TYPE The file type Allowed values are MODE WHEN
112. meter zr It must lie within its corresponding bounds Moreover you are not allowed to assign a value different than the current one if parameter xr is fixed 9 1 5 SUBROUTINE GETG Definition SUBROUTINE GETG GRAD REAL GRAD Purpose Returns the gradient vector evaluated at the current point using the derivative mode currently in effect Arguments e GRAD output The gradient vector with GRAD 2 corresponding to or Array GRAD should have at least N storage locations available GRAD 2 is set to zero if parameter z is fixed 9 1 6 SUBROUTINE GETG1 Definition SUBROUTINE GETG1 I GI INTEGER I REAL GI 118 MERLIN glue routines Purpose Returns one of the components of the gradient vector evaluated at the current point using the derivative mode currently in effect Arguments I input Index of the parameter whose derivative is to be returned e GI output The first partial derivative with respect to parameter zr If parameter zr is fixed GI is set to zero 9 1 7 SUBROUTINE GETHES Definition SUBROUTINE GETHES H LD HOW REAL H LD INTEGER LD CHARACTER HOW Purpose Returns the Hessian matrix Arguments e H output The lower triangular part of H contains the second partial derivatives 2f Mag n 101 j i 1 N j 1 i The contents of the rest of the matrix are undefined Matrix H should have at least N storage locations available e LD input The leading dimension of matrix H
113. nj oATyelqo oy Jo ydel13 euru y3no e SIYEN soser e peuyop Austins y s e dsi uomnrug p See ue SIAQUISYH sere ue souyod ssey Jopoereyo NITUAJ 979 s e dst T S384 NITHAJA ey skeTdstq SIEH Jopoeseyo NITHAJA Y 0 SON LA susissy S384 NITHAJ OY 0 Sonea susissy ay Y SPULMIH UOTJLULIOJUI JO PUd y 0 OT Y SUOTIISOg y V JO syuaquoo ay syoedsu y Y 03 saynqizyye pue qurod yusrINI ay s 1o1 Y e ur Mq Aue 10 YUIOd Jqu imo IY S JNAA SIP WOI Y Y SoAOWOI ATJUSURUTIE Y soynqiiyye pue urod quemo 97 YIM AY Y SOJLIMISA UOTJENTLAD uomounj Ss 9 qeSI T uomnenreA9 uonounj s qeurq NASINS ANTLNOYANS peyddns sn Y 89 09 NITH3 N Syonsysuy NIWNNA NOILLONNA pariddns 19sn oy 189 ol NITUAIN I9N1ISU qndyno re sesserddng paAe dstp oq o s 3essow 10110 ATUO sAo V paAe dstp oq 0 yndyno TM sAollV 92U949J9H9 MOMO NITYAIW gt puvwwos jpuvd 330TANYd pupwwuoo jaund NOTANYd DOTIAHON bof uanga LIND DOTIAAON NUNLAY DOTIdHON dOLS puounuoo2 jauvd HIVUDSA puvwuwos jauod Hava SIGSVITV IWDU sn SVITVNO pupnturuoo tupu SDID SVLIV caput SICOVIAD zapu SIA YTA oes IN JDA LIJIDADYI TIPpUI DVIAO PASA 9N DA TIPpUI VIA SPUDULUWOI SNOIUD IISt A tupu nf NIMH e tupnu lnf A0109 puounuoo2 2940d LOAdSNI puvwwos 940d OWAN puvwwos 29uod anna awwuf ALATA a9wuDu 24 CUVISIA SPUDWULOD PIJDIIA 9H IVAHON ALVNIVAd SoS TWUANndd LNIdON
114. nt method PR FR GPR GTOL G convergence criterion 0 lt real lt 1 XTOL X convergence criterion 0 lt real lt 1 FTOL F convergence criterion 0 lt real lt 1 ITER Iterations 1 Inf Any int gt 1 RESTART N step restart No Yes 0 1 MAD Automatic derivatives On Off USEG Use Recalculate gradient 1 0 LSITER Max LS iterations Any int gt RHO Line search rho 0 lt real SIGMA Line search sigma 0 lt real METHOD GTOL XTOL FTOL ITER RESTART MAD CANCEL Cancel Proceed 0 1 Figure 6 9 The CONGRA panel Determines the method to use Allowed values are e PR Use the Polak Ribiere formula e FR Use the Fletcher Reeves formula e GPR Use the generalized Polak Ribiere method of Khoda Liu and Storey The gradient termination criterion The method terminates when the relative gradient falls below GTOL Termination criterion based on the values of the parameters The method terminates when the relative change in the parameters in two successive iterations is less than XTOL Termination criterion based on function values The method terminates when the rela tive function drop in two successive iterations is less than FTOL The number of iterations to perform A value of 1 allows an unlimited number of iterations Specifies whether the N step restart should be taken Allowed values are e 0 Do not use the N step restart e 1 Reset the search direction to th
115. o variables zs through n the value 1 2 6 2 2 INIT Syntax classification PAC Purpose Assigns names or values stored in a file to minimization parameters In addition it can be used to assign values stored in a file to either the lower or upper bounds to the fix status of the variables or to the search steps for the ROLL method The associated panel is listed in figure 6 1 The panel parameters are as follows FILE The file holding the appropriate data WHAT Specifies what to initialize Allowed values are Attribute related commands 41 eX Read in the current point eL Read in the left margins eR Read in the right margins e F Read in the fix statuses 1 for a free variable 0 for a fixed one eS Read in the search steps used by the ROLL command eN Read in the symbolic names of the parameters NPL Specifies how many numbers will be read from each line of the file This does not apply to symbolic names which are always read one per line Setting NPL to 0 lets the system decide for the actual numbers per line SKIP Determines an initial number of lines to be skipped before actually reading initialization data FROM Specifies the index to start the initialization TO Specifies the index to end the initialization FORMAT Thisis the format to be used when reading data from the file You may specify any valid Fortran format or to use a free format Note that the format must be consistent with the setting of NPL c
116. og 8 3 6 HAS_APPEND Syntax Purpose Default Used by Examples HAS_APPEND append_status Specifies whether your Fortran compiler supports the APPEND extension in an OPEN statement More specifically whether the following is a valid Fortran statement OPEN UNIT unit_number FILE file_name ACCESS APPEND The APPEND extension allows much faster updating of large text files eg those produced by the MERLIN backup mechanism or by the MEMO command append_status cane be either yes or no If this directive is omitted it defaults to HAS_APPEND no i e the APPEND extension is not used MERLIN only HAS_APPEND yes 8 3 7 SIZE_REAL Syntax Purpose SIZE_REAL n Specifies that a floating point Fortran variable occupies n storage locations in an un formatted file Floating point refers to a real or double precision variable depending on the installation n is used to calculate the appropriate RECL specifier when opening a MERLIN binary file OPEN UNIT unit_number FILE file_name RECL record_length File related directives 109 Default Used by Examples If this directive is omitted SIZE_REAL defaults to 4 which is appropriate for double precision variables in most 32 bit computer systems MERLIN only SIZE_REAL 4 8 3 8 SIZE_INT Syntax Purpose Default Used by Examples SIZE_INT n Specifies that an integer Fortran variable occupies n storage locations in an unfor
117. oints evaluations in case one wants to plot the objective function Along with TO this parameter determines the interval over which the function is plotted This interval refers to the variable specified by INDEX Along with FROM this parameter determines the interval over which the function is plotted This interval refers to the variable specified by INDEX In case one wants to plot a set of data points this is the file containing these points The points should be stored column wise with the first column being the X values and the rest of the columns being sets of Y values that correspond to different curves Spaces or tabs can be used to separate the numbers in a line Specifies whether a symbol should be plotted at each data point Allowed values are e 0 Do not plot a symbol 80 XTITLE YTITLE FONTSIZE GRID FRAME CONNECT XTICKS YTICKS PAPER CANCEL Command description e 1 Plot a symbol an x at each data point The X axis title The Y axis title The X and Y axis titles are printed using the Times Roman font and this font size Specifies whether grid lines should be plotted Allowed values are e 0 Do not plot grid lines el Plot grid lines Specifies whether a frame should be plotted around the graph Allowed values are e 0 Do not plot a frame around the graph el Plot a frame around the graph Specifies whether the data points should be connected by a straight line or not Allowe
118. on next page 38 Curve fitting A complete example continued from previous page shortdis SHORTDIS Title Curve fitting using a cubic polynomial Number of evaluations Total Since last reset Index Name 1 2 3 4 Z NAA AVAVA leve noc 100 LEVE Parameter value Left margin Right margin 22 9000000000000 1 10000000000000 1 10000000000000 11 4000000000000 1623492 70661034 Merlin is at your command Start the minimization using the Levenberg Marquardt method value 1623492 70661034 Calls 1 of 100 Calls 2 of 100 Calls 3 of 100 Function evaluations Jacobian evaluations Iterations NVAM AA NN shortdis SHORTDIS Merlin is at your command Title Curve fitting using a cubic polynomial Number of evaluations Total Since last reset Index Name 1 2 3 4 NAN A NAVN stop Parameter value Left margin Right margin 3 85673558101135 1 37311723433982 1 71949888365997 7 585181298786750E 02 9 484394200265485E 03 Merlin is at your command We are done Good bye Chapter 6 Command description 6 1 Command classification There are several ways in which the commands can be grouped together In presenting the com mands a grouping based on the context relevance is used However a grouping according to the syntax format is also convenient for the command description Hence some definitions are given below for the several syntax categories 1 Simp
119. ontaining the appropriate number of format specifiers Symbolic names are always read one per line using an A format CANCEL This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended 6 2 3 PICK Syntax classification PAC Purpose Assigns values for all the parameter attributes by reading a specially formatted file Such files may be created by other MERLIN commands MEMO DISCARD BACKUP The associated panel is listed in figure 6 2 The panel parameters are as follows FILE The file to pick from TYPE The file type Allowed values are e TEXT fora MERLIN text file Information is stored in human readable ASCII form Slower but portable 42 Command description Ind Keyword Description Allowed values 1 FILE File to pick from Any string 2 TYPE File type Text Bin 3 REC Record to pick Any int gt 0 4 CANCEL Cancel Proceed 0 1 Figure 6 2 The PICK panel e BIN for a MERLIN binary file Information is stored in binary machine dependent form Faster but less portable REC The record to pick from the specified file CANCEL This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is th
120. orresponds to In case of a plug in module it is the name assigned to the plug in through the PLUG configuration directive It must be up to 10 characters long and is case insensitive panel_status Initial setting for the panel status It can be either on or off The panel status is changed by the PANELON and PANELOFF commands Examples panel bfgs on panel memo off The panel description file 97 SUBROUTINE PEXA CHARACTER 80 FNAME CALL CHANGE MERR IF MERR NE O THEN CALL SETCOD MERR RETURN END IF CALL GETPI FROM NFROM CALL GETPI TO NTO CALL GETPS FILE FNAME LEF NU NUNIT OPEN NU FILE FNAME DO 10 I NFROM NTO CALL GETX1 1 XI WRITE NU XI CONTINUE CLOSE NU NL NTO NFROM 1 CALL SETPI LINES NL IERR CALL SETCOD 0 END Present the panel and accept changes Check if any error occurred Indicate an error Get index to start from NFROM Get index to end to NTO Get the file name FNAME Obtain a free unit number NU Open the file Loop over the specified parameters Get the Ith parameter XI Write the parameter Close the file Calculate the number of lines written NL Return the number of lines written Indicate no error Figure 7 6 Sample plug in module that exploits the panel mechanism It uses the glue routines CHANGE SETCOD GETPI GETPS NUNIT GETX1 and SETPI 98 Extensions PANEL PEXA ON FROM 1 1 inf 1 Index to begin from T
121. pears displaying these newly substituted values and prompts for additional input In the second case keyword keywordz assume the values value valuez which are substituted in the panel The panel_command is not executed however and no panel appears 4 3 Output handling MERLIN produces two kinds of output the informative normal output and the error output Nor mal output is produced by almost every command while error output results when some abnormal situation is encountered The amount of output produced by MERLIN is controlled by the com mands FULLPRINT HALFPRINT and NOPRINT that set the options for the printout mode Note that 24 The MERLIN Operating System some commands contain options most notably the PRINT keyword in all minimization command panels that allow further control on the output when the FULLPRINT option is in effect MERLIN output may be temporarily redirected from its normal destination a terminal or a file to any file using the gt and gt gt symbols followed by a filename For example the command SHORTDIS gt result redirects the output of the SHORTDIS command to a file named result overwriting its previous contents The symbol gt gt appends the output to the contents of an already existing file Note that both the normal as well as the error output are redirected The effect of output redirection can be facilitated for a number of subsequent commands using a pair of HIDEOUT REVEA
122. pecifies the index to start writing from File manipulation commands 75 TO VALUE FORMAT CANCEL Specifies the index to end writing to Specifies whether the value of the objective function is to be written Allowed values are e BEFORE The value of the objective function is written before the actual data e AFTER The value of the objective function is written after the actual data e NEVER The value of the objective function is not written This is the format to be used when writing data to the file You may specify any valid Fortran format or to use a free format Note that the format must be consistent with the setting of NPL containing the appropriate number of format specifiers Symbolic names are always written one per line using an A format This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended 6 8 3 DISCARD Syntax classification UNC Syntax DISCARD filename TEXT BIN Purpose Writes a MERLIN record with the values and attributes of the minimization parameters to a specified file The file is overwritten The optional parameter at the end of the command specifies the file type Examples DISCARD DATAFILE overwrites the file DATAFILE with the values and attributes of the min
123. r the backup If it matches the ones defined in the backup panel then backup will proceed MERLIN uses the following conventions WHEN M or WHEN m A backup record is added when a minimization command terminates WHEN X or WHEN x A backup record is added before the current point is changed by a POINT INIT or PICK command WHEN D or WHEN d A backup record is added before one of the attributes margin fix status or symbolic name of the minimization parameters is changed WHEN L or WHEN 1 A backup record is added when a lower value is discovered by one of the minimization routines 9 4 23 FUNCTION ISIAF Definition INTEGER FUNCTION ISIAF Purpose Returns 1 if the IAF processing mode is in effect 0 otherwise Processing modes are switched using the IAF and BATCH commands 142 MERLIN glue routines 9 4 24 FUNCTION ACSQ Definition Purpose Arguments REAL FUNCTION ACSQ X N INTEGER N REAL X N All MERLIN minimization methods that operate on general functions not on sum of squares call this routine It contains a counter and updates some common block pa rameters Its value is set equal to the user supplied FUNCTION FUNMIN or SUBROUTINE SUBSUM according to the functional form GENERAL or SOS X input The minimization parameters with X i corresponding to zi N input Dimensionality of the objective function 9 4 25 SUBROUTINE LS
124. rams Minimization related commands 55 FCALLS Number of function evaluations that were performed GCALLS Number of evaluations of the gradient vector ITERDONE Number of BFGS iterations that were performed RADIUS The final trust region radius INFO Result code Possible values are e 1 The target value has been reached e 2 The gradient criterion is satisfied e 3 All function evaluations have been used e 4 The minimization parameters have converged e 5 The function value has converged e6 The Hessian matrix cannot be updated e 7 The specified number of iterations has been reached e 8 All variables are fixed e 9 Further progress is not possible 6 3 7 CONGRA Syntax classification PAC Purpose Invokes any of the three implemented conjugate gradient algorithms These are e The Polak Ribiere algorithm e The Fletcher Reeves algorithm e The Generalized Polak Ribiere algorithm The associated panel is listed in figure 6 9 The panel parameters are as follows NOC An approximate upper bound for the number of calls to the objective function PRINT Determines the amount of output from the minimization method Allowed values are e0 No printout at all e 1 Display lower function values as they are discovered e 2 Display function and parameter values as well 56 Command description Keyword Description Allowed values NOC Number of calls Any int gt 1 PRINT Printout level 0 1 2 METHOD Conjugate gradie
125. ring to its numeric representation Leading or trailing blank or tab characters in the string are ignored e STR input The string to be converted e LE input The effective length of STR e N output The integer representation of STR e IERR output An error code indicating whether the conversion was successful Possible values are IERR 0 Conversion was successful IERR 2 Conversion failed STR does not contain a proper integer number 9 3 4 SUBROUTINE TOREAL Definition Purpose Arguments SUBROUTINE TOREAL STR LE R IERR CHARACTER STR INTEGER LE REAL R Converts a real number from its string to its numeric representation Leading or trailing blank and tab characters are ignored The number should be of the form mt frac exp where int is the integer part a sequence of digits frac is the fractional part another sequence of digits and exp is the exponent The integer part int or the fractional part frac may be omitted but not both The exponent exp should have the form E e D d int e STR input The string to be converted Utility glue routines 131 e LE input Effective length of STR e R output The converted real e TERR output An error code indicating whether the conversion was successful Possible values are IERR 0 Conversion was successful IERR 2 Conversion failed STR does not contain a proper real number 9 3 5 FUNCTION ISCOMP
126. rion is satisfied e 3 All function evaluations have been used e 4 The X convergence criterion is satisfied e5 The function value has converged e 7 The specified number of iterations has been reached e 8 Further progress is not possible e 9 All variables are fixed 58 Keyword Description NOC Number of calls PRINT Printout level GTOL G tolerance XTOL X tolerance FTOL F tolerance FACC Function accuracy CANCEL Cancel Proceed Figure 6 10 The LEVE panel 6 3 8 LEVE Syntax classification PAC Command description Allowed values Any int gt 1 0 1 2 0 lt real lt 1 0 lt real lt 1 0 real lt 1 0 lt real lt 1 0 1 Purpose Invokes a Levenberg Marquardt type of algorithm for a sum of squares objective function The associated panel is listed in figure 6 10 The panel parameters are as follows NOC PRINT GTOL XTOL FTOL FACC CANCEL An approximate upper bound for the number of calls to the objective function Determines the amount of output from the minimization method Allowed values are e 0 No printout at all e 1 Display lower function values as they are discovered e 2 Display function and parameter values as well The gradient termination criterion The method terminates when the relative gradient falls below GTOL Termination criterion based on the values of the parameters The method terminates when the relative change in the parameters in two successiv
127. ro composing session that prompts for the macro name and the constituent commands and finally appends the resulting macro in file MACROF To terminate the macro composition one must use the CLEAR command Data fitting related commands 83 Ind Keyword Description Allowed values 1 DO Desired action c r w 2 PROB Confidence Probability 0 lt real lt 1 3 FILE File name Any string 4 CANCEL Cancel Proceed 0 1 Figure 6 21 The COVARIANCE panel 6 12 2 CLEAR Syntax classification SIC Purpose Used to terminate a macro composing session initiated by command MACRO It has no effect outside a MACRO session 6 12 3 RUNMCL Syntax classification UNC Syntax RUNMCL filename Purpose Initiates execution of a precompiled MCL program that resides in the specified file Equivalent syntax filename 6 13 Data fitting related commands 6 13 1 COVARIANCE Syntax classification PAC Purpose Calculates the covariance matrix for a least squares fit The associated panel is listed in figure 6 21 The panel parameters are as follows DO Specifies the action to be taken Allowed values are e C Calculate the covariance matrix eR Read the covariance matrix from a file eW Calculate and store the covariance matrix in a file PROB The probability that is used to define the confidence region 84 Command description FILE The file to store or read from the covariance matrix The matrix is stored column wise and may be la
128. rpose Returns the symbolic name of one of the minimization parameters Arguments I input Index of the parameter whose name is requested e NAMEI output The symbolic name of parameter zr Variable NAMEI should be at least 10 char acters long If no symbolic name has been set for parameter zr NAMEI is left blank 9 2 Panel related glue routines These routines manipulate the values assigned to the keywords of the various panels The GETP and SETP series of subroutines always operate on the panel of the current command while the GETPP and SETPP series operate on any panel 9 2 1 SUBROUTINE GETPI Definition SUBROUTINE GETPI KEY IVAL CHARACTER KEY INTEGER IVAL Purpose Subroutine GETPI returns the integer value IVAL assigned to the keyword KEY in the current panel Arguments e KEY input The keyword to search for It must exist in the panel of the current command and have an integer type otherwise this routine will abort e IVAL output The integer value that corresponds to the keyword 9 2 2 SUBROUTINE GETPR Definition SUBROUTINE GETPR KEY RVAL CHARACTER KEY REAL RVAL Panel related glue routines 123 Purpose Subroutine GETPI returns the floating point value RVAL assigned to the keyword KEY in the current panel Arguments e KEY input The keyword to search for It must exist in the panel of the current command and have a real type otherwise this routine will abort e RVAL output The rea
129. rs must be recorded in a configuration file named CONFIG that is read by MERLIN and MCL as well In fact the purpose of the configuration file is twofold Machine dependent parameters can be specified in CONFIG On the other hand the configuration file is used to alter the defaults until one reaches the MERLIN prompt Each line of the configuration file contains a configuration directive The default name can be changed during installation using the CONFIG installer macro 10 Installation and configuration This line is a comment since it starts with the character The largest floating point number BIGGER 1 D300 Z The smallest positive distinguishable from zero floating point number SMALLER 1 D 300 This system uses some peculiar input output units INPUT_UNIT 9 OUTPUT_UNIT 9 Figure 2 2 Sample configuration file directive parameter parameterg parameter As usual to embed spaces in a parameter you must enclose it in a pair of singe quotes Lines starting with the percent character comments and blank lines are ignored The contents of a typical configuration file are shown in figure 2 2 The directives INPUT_UNIT and OUTPUT_UNIT refer to the input and output unit correspondingly while directives BIGGER and SMALLER refer to the largest and smallest positive distinguishable from zero floating point numbers There more directives that change the defaults and control the behavior of MERLIN during s
130. rs can be returned to MCL programs REC Index of the last record that has been inspected 6 9 Graphics and related commands 6 9 1 GRAPH Syntax classification PAC 78 Command description Keyword Description Allowed values INDEX Variable index Any int gt NOP Number of points Any int gt FROM From Any real T To Any real LINES Lines Any int gt COLS Columns Any int gt 1 CANCEL Cancel Proceed 0 1 Figure 6 19 The GRAPH panel Purpose Displays a one dimensional rough graph of the objective function with respect to one of its parameters The associated panel is listed in figure 6 19 The panel parameters are as follows INDEX NOP FROM TO LINES COLS CANCEL The function is graphed with respect to this variable Number of points for the graph Each point corresponds to an evaluation of the objective function Along with TO this parameter determines the interval over which the function is dis played This interval refers to the variable specified by INDEX Along with FROM this parameter determines the interval over which the function is displayed This interval refers to the variable specified by INDEX The number of lines to use The number of columns to use This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the proces
131. s advances normally e 0 cancels the action initially intended 6 9 2 PSGRAPH Syntax classification PAC Purpose Produces a Postscript graph of the objective function or of a set of X Y data points The associated panel is listed in figure 6 20 The panel parameters are as follows WHAT Specifies what to plot Allowed values are Graphics and related commands FILE INDEX NOP FROM TO DATAFILE SYMBOL Keyword WHAT FILE INDEX NOP FROM TO DATAFILE SYMBOL XTITLE YTITLE FONTSIZE GRID FRAME CONNECT XTICKS YTICKS PAPER CANCEL Description What to plot Func Data Output file name Variable index Number of points From To Data file to read Symbol No Yes X axis title Y axis title X and Y title fontsize Grid lines On Off Frame On Off Connect points Yes No Number of X axis ticks Number of Y axis ticks Paper A4 B5 USLet USLeg Cancel Proceed Figure 6 20 The PSGRAPH panel 79 Allowed values f d Any string Any int gt 1 1 lt int lt Any real Any real Any string 0 1 Any string Any string 5 lt int lt 1 0 1 0 1 0 O lt int lt O lt int lt 0 1 2 3 0 1 e F Plots the objective function with respect to one of its variables e D Plots X Y curves from data points stored in a file The file to dispose the PostScript graph The objective function is plotted with respect to this variable 1000 Number of p
132. s directive is omitted the name of the MERLIN macro file defaults to MACROF MERLIN only MACRO_FILE macrol MACRO_FILE HD merlin supermac 8 3 3 HELP_FILE Syntax Purpose Default Used by Examples HELP_FILE filename Sets the name of the MERLIN help file to file_name If this directive is omitted the name of the MERLIN help file defaults to HELP MERLIN only HELP_FILE extrahelp 8 3 4 MCL_ERROR_FILE Syntax Purpose Default Used by Examples MCL_ERROR_FILE file_name Sets the name of the default Mct error file to filename When the an error file E file_name is not supplied when the MCL compiler is invoked the error file defaults to this value Setting filename to an empty string MCL_ERROR_FILE causes all compiler diagnostics to be printed on the standard output unit If this directive is omitted all compiler diagnostics are printed on the standard output unit MCL only MCL_ERROR_FILE errors MCL_ERROR_FILE errs job1 108 The MERLIN MCL configuration file 8 3 5 MCL_OBJECT_FILE Syntax Purpose Default Used by Examples MCL_OBJECT_FILE filename Sets the name of the default MCL object file to filename When the an object file B file name is not supplied when the MCL compiler is invoked the object file defaults to this value if this directive is omitted MCL_OBJECT_FILE defaults to MOC standing for MERLIN Object Code MCL only MCL_OBJECT_FILE mypr
133. s name must be declared in the MERLIN configuration file e In case the plug in obtains its input using the panel mechanism one must make the corre sponding entries in the panel description file These steps are further explained in the following sections 7 2 Writing the plug in module Let us assume that one wants to create an alternative to SHORTDIS a plug in module that will print the value of the parameters their names if any and their first partial derivatives A sub routine that performs the desired operation is shown in figure 7 1 Sample output for the two parameter Rosenbrock function is demonstrated in figure 7 2 As is clear from the example to 91 92 Extensions SUBROUTINE NEWSH CHARACTER 10 NI CALL GETIOU IUINP IUOUT Find out the output unit number IUOUT CALL GETDIM N M Find out the number of parameters N DO 10 1 1 N Loop over all parameters CALL GETX1 1 XI Get the value of the I parameter XI CALL GETNM1 1 NI Get the name of the I parameter NI CALL GETG1 1 G1 Get the Ith component of the gradient GI WRITE IU0UT 20 I NI XI GI Print them all out CONTINUE FORMAT 2X 15 2X A 2 2X 1PE14 7 END Figure 7 1 Sample plug in module an alternative to SHORTDIS It uses the glue routines GETIOU GETDIM GETX1 GETNM1 and GETG1 1 Rho 4 0000000E 00 1 9206000E 04 2 Sigma 4 0000000E 00 2 4000000E 03 Figure 7 2 Output from the sample plug in module NEWSH Naming the plug in mod
134. s of calculating the Hessian matrix eR Read the Hessian matrix from a file eW Write the Hessian matrix to a file USE If the calculation of the Hessian was requested USE determines the method of calcula tion Allowed values are e F Use function values only O f x y Ay f x i h y i f x i h y f x y 0 f x y ro OxOy h For the diagonal elements d2f _ J e 2h 2f z h f z de h2 with h 3 7 max 1 x and similarly for eG Use the user supplied SUBR0UTINE GRANAL a f z y x 7 ae EN r y 2 1 pre h 0f x y Oy Oy i Ox Ox For the diagonal elements Tial da h with h m max 1 x and similarly for e A Use the user supplied SUBROUTINE HANAL Ofla h Of az Ox Ox MODE1 If comparison of two methods for calculating the Hessian matrix was requested MODE1 specifies the first mode of calculation Allowed values are e F Use function values only eG Use the the user supplied SUBROUTINE GRANAL that returns the first partial deriva tives 66 MODE2 FILE CANCEL Command description e A Use the user supplied SUBROUTINE HANAL that returns the Hessian matrix If comparison of two methods for calculating the Hessian matrix was requested MODE2 specifies the second mode of calculation Allowed values are e F Use function values only eG Use the the user supplied SUBROUTINE GRANAL that returns the first partial deriva
135. sing either their keyword or their index in the panel For example for the BFGS panel shown above any of the following two lines can be used invariably for input NOC 1000 PRINT 2 1 1000 2 2 An empty line signifies no changes Parameters that are changed are recorded by the panel and appear the next time the command is invoked Panels also communicate information to an MCL program upon completion of a command s execution a subject covered in a later section Each panel may be active on or inactive off Active panels appear and prompt the user for changes when the associated command is invoked Inactive panels do not appear their stored values are automatically used by the command Panels are turned on or off with the commands PANELON and PANELOFF correspondingly If used without an accompanying argument these commands turn on or off all MERLIN panels Arguments may be used to alter the status of some of the panels For example the command PANELOFF BFGS DFP turns off the panels associated with the commands BFGS and DFP The status of all panels can be displayed with the PSTATUS command Panel commands can use a syntax involving two special characters the semicolon and the exclamation as directives in the following way panel_command keyword value keyworda values panel_command keyword value keyworda values In the first example keyword keywords assume the values value valuez The panel ap
136. ssible values are MEC Neither an upper nor a lower bound has been set for parameter zi MFG 1 An upper bound has been set for parameter zi MFG 1 A lower bound has been set for parameter zi MFG 2 Both an upper and a lower bound have been set for parameter z 120 MERLIN glue routines e XL output XL 1 stores the lower bound on parameter z If z has no lower bound a large negative number is returned e XU output XU z stores the upper bound on parameter x If x has no upper bound a large positive number is returned 9 1 10 SUBROUTINE GETMR1 Definition SUBROUTINE GETMR1 I MFI XLI XUI INTEGER I MFI REAL XLI XUI Purpose Returns the upper and lower bound for one of the minimization parameters Arguments I input Index of the parameter whose bounds are requested e MFI output Indicates whether the specified parameter has a lower upper or both bounds Possible values are MFI 0 Neither an upper nor a lower bound has been set for parameter zr MFI 1 An upper bound has been set for parameter zr MFI 1 A lower bound has been set for parameter zr MFI 2 Both an upper and a lower bound have been set for parameter zr e XLI output The lower bound If a lower bound has not been set a large negative number is returned e XUI output The upper bound If an upper bound has not been set a large positive number is returned 9 1 11 SUB
137. stem upon termination of the plug in Although in general a non zero value indicates that something went wrong MERLIN uses the following conventions MERR 0 No error occurred during execution of the plug in MERR 1 An end of file condition was encountered while trying to read from the MERLIN input unit MERR 2 Some other error occurred during execution of the plug in By following the above conventions one makes sure that an error condition will be treated appropriately by the MERLIN error handling routines taking into account the current processing mode IAF or BATCH If a plug in module terminates without setting the error code a value of zero is assumed Example SUBROUTINE PLUG1 do something here IF some error THEN MERR 2 ELSE MERR 0 CALL SETCOD MERR END 9 4 12 FUNCTION ISMCL Definition INTEGER FUNCTION ISMCL Purpose Returns 1 if MERLIN is running an MCL program 0 otherwise 9 4 13 SUBROUTINE GETIOU Definition SUBROUTINE GETIOU NIN NOUT INTEGER NIN NOUT Miscellaneous glue routines 137 Purpose Returns the MERLIN input output units In order to maintain compatibility with the rest of the environment write operations on the MERLIN output unit should take in account the printout levels as returned by SUBROUTINE GETPRL Arguments e NIN output The MERLIN input unit Input should always be read from this unit e NOUT output The MERLIN output unit Outpu
138. su ae a ee ee a a 130 9 3 5 FUNCTION ISCOMP 2 usun Boe we how eR a he WE we Ge eas 131 9 30 FUNCTION LENGTH sorcu each A at eae a Ew A a a 131 Miscellaneous glue routines 2 2 e 132 9 4 1 SUBROUTINE GETDIM Nori sou a cs GS ee ea a Ew ae 132 9 4 2 SUBROUTINE ARGND Sna sos a ee ee oe Pa Boe w E oe Bee eg 132 9 4 3 SUBROUTINE GETARG 2 2 a e a a saa sss e 132 9 4 4 SUBROUTINE GETACC e 133 Contents 9 4 5 9 4 6 9 4 7 9 4 8 9 4 9 9 4 10 9 4 11 9 4 12 9 4 13 9 4 14 9 4 15 9 4 16 9 4 17 9 4 18 9 4 19 9 4 20 9 4 21 9 4 22 9 4 23 9 4 24 9 4 25 vil SUBROUTINE GETMG o oo ee he ee OU W Aw OE 6 ee Be 133 SUBROUTINE GETCNT saa ga a Wk ee Ge ee ee ee es 133 SUBROUTINE GETFLA w sis we e A ew Op a OS iow US 134 SUBROUTINE SETEBA ico acta doe A eV YS 134 SUBROUTINE GETCEL v os h i cadd Be a ga da dama A 135 SUBROUTINE SET FL ui A a ed AA A GS 135 SUBROUTINE SETCOD 3 00 s ah yy a a a Ble re eh ee a aes 135 FUNGCTAON TSMCE 5 inimi ok seid koa Aiea die W deat Acie died a At Ada cai oh ke acd 136 SUBROUTINE GETIDU nisge Seok Sa A ee ea ge kd Ba ae S hua a 136 SUBROUTINE GETPRE u 2 ss doce ls Ae in ee ee A ce A A tid 137 SUBROUTINE GEEVAL ic nee 2 2 ete eee E ae Pee oe Hera Ei Std 138 SUBROUTINE SETVAL J a ak wala ble be abies kup kee See Sh os 138 SUBROUTINE GETEVM fidya tode ae Son SU a A ee Se a 138 SUBROUTINE GETFFO 2 ku p An abu sm
139. t should always be written to this unit Example LOGICAL STRO WEAK CALL GETPRL STRO WEAK CALL GETIOU NIN NOUT IF STRO WRITE NOUT An informative message IF WEAK WRITE NOUT An error message 9 4 14 SUBROUTINE GETPRL Definition SUBROUTINE GETPRL STRO WEAK LOGICAL STRO WEAK Purpose Returns a set of logical variables that control the display of MERLIN output In order to maintain consistency with the rest of the environment the same conventions should be used in a plug in module Arguments e STRO output Logical variable that controls the display of normal output Possible values are STRO TRUE Normal output should be displayed STRO FALSE Normal output should be inhibited e WEAK output Logical variable that controls the display of error output Possible values are WEAK TRUE Error output should be displayed WEAK FALSE Error output should be inhibited Example See SUBROUTINE GETIOU 138 MERLIN glue routines 9 4 15 SUBROUTINE GETVAL Definition SUBROUTINE GETVAL VALUE REAL VALUE Purpose Returns the current value of the objective function Note that you cannot request the value of the objective function if it has not been evaluated at least once You can test this using the MERLIN call counters Arguments e VALUE output The current value of the objective function 9 4 16 SUBROUTINE SETVAL Definition SUBROUTINE SETVAL VALUE REAL VALUE
140. tartup they are explained in detail in chapter 8 Chapter 3 User written programs MERLIN offers an optimization environment supplies several utility as well as minimization tools so that the user can choose whatever is convenient and effective each time The programs the user may have to write are the following 1 The main program 2 The objective function in a general or in a sum of squares form 3 The gradient vector optional 4 The Jacobian matrix optional 5 The Hessian matrix optional In what follows we give sample programs coded in single precision These should be used with a single precision installation If double precision is needed which is quite often the case one should use a double precision installation and code these programs in double precision 3 1 The main program The role of the main program is to initiate MERLIN s execution The user may write his own main program or may use the sample provided below modified appropriately to meet his needs To invoke MERLIN one should make a call to the subprogram SUBROUTINE MERLIN N M VERSIM MAXW IQUIT N input is the dimensionality of the problem 11 12 M VERSIM workspace MAXW IQUIT input input output User written programs is the number of the squared terms useful for the sum of squares form is a work space array dimensioned as VERSIM MAXW max N N 11 NM is an output flag that is either sp
141. tax TITLE title_text Minimization related commands 45 Keyword Description Allowed values NOC Number of calls Any int gt 1 PRINT Printout level 0 1 2 FAIL Failures allowed Any int gt SFACTOR Step factor Any real gt FTOL Min relative drop 0 lt real LSNOC Line search calls Any int gt LSTOL Line search tolerance 0 lt real CANCEL Cancel Proceed 0 1 Figure 6 3 The ROLL panel Purpose Sets a short title for the run The title appears on top of the output produced by the SHORTDIS command Examples TITLE Rosenbrock Test Function 6 2 16 RESET Syntax classification SIC Purpose Resets to zero the partial counters for the calls to the objective function to the user supplied code for the gradient SUBROUTINE GRANAL the Jacobian SUBROUTINE JANAL and the Hessian SUBROUTINE HANAL 6 3 Minimization related commands 6 3 1 ROLL Syntax classification PAC Purpose Invokes the Roll minimization algorithm The associated panel is listed in figure 6 3 The panel parameters are as follows Noc An approximate upper bound for the number of calls to the objective function PRINT Determines the amount of output from the minimization method Allowed values are e0 No printout at all e 1 Display lower function values as they are discovered 46 FAIL SFACTOR FTOL LSNOC LSTOL CANCEL Command description e 2 Display function and parameter values as well The number of successive c
142. ter used by the CONFIDENCE command CANCEL This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended 6 13 2 CONFIDENCE Syntax classification RAC Purpose Displays the equation defining the confidence region for a least squares fit 6 14 Getting help There are two commands that provide useful information on the usage of MERLIN 6 14 1 LIST Syntax classification SIC Purpose Lists alphabetically all MERLIN commands The command s output is listed in figure 6 22 6 14 2 HELP Syntax classification UNC Syntax HELP comand_name Purpose Provides on line instructions for the usage of all MERLIN commands Examples HELP POINT produces the output listed in figure 6 23 Getting help BACKUP CONFIDENCE DISCARD FIX GENERAL GRAPH IAF LASTBACK LOOSALL MODEDIS NUMER PSGRAPH RETURN SHORTDIS STOP UNALTAS ADJUST BATCH CONGRA DUMP FIXALL GNORM HALFPRINT INIT LDEMARGIN LOOSE NOBACK PANELOFF PSTATUS REVEAL SIMPLEX TARGET VALDIS CONTROL ECHO FLAG GODFATHER HELP INSPECT LEVE MACRO NOEVAL PANELON QUAD REWIND SOS TERMDIS ALTASDIS CFLAG COVARIANCE EPILOG FLAGDIS GOEOF HESSIAN JANAL LIMITS MAD NONAME PDUMP QUIT RMARGIN STEP TITLE CFLAGDIS DELETE EVALUATE FULLBA
143. tives during minimization e IAUTO output Specifies whether the MERLIN automatic derivatives should be enabled or dis abled Possible values are IAUTO 0 Automatic derivatives are disabled IAUTO 1 Automatic derivatives are enabled CALL SETADE 1 call some user minimization routine CALL SETADE 0 9 4 21 FUNCTION NUNIT Definition Purpose INTEGER FUNCTION NUNIT Function NUNIT will search a range of unit numbers in order to locate an unused unit a unit not assigned to an open file Function NUNIT is a necessity since Fortran requires both a unit number and a file name in an OPEN statement Nevertheless function NUNIT and all of the MERLIN file handling routines rely on the Fortran INQUIRE statement and especially on the OPENED EXIST NUMBER and IOSTAT specifiers The range of numbers to be searched can be set from the configuration file using the UNIT_RANGE directive For efficiency the search for the unit number starts from the number returned in the previous NUNIT call not from the beginning of the available range Miscellaneous glue routines 141 Example NU NUNIT IF NU EQ 1 THEN display error message ELSE OPEN NU FILE some file END IF 9 4 22 SUBROUTINE BACKUP Definition SUBROUTINE BACKUP WHEN CHARACTER WHEN Purpose Adds a record to the backup file according to the modes specified in the backup panel Arguments e WHEN input Character variable indicating the reason fo
144. ule 93 access information about the minimization parameters and the MERLIN operating environment we use a number of routines GETDIM GETIOU GETX1 GETNM1 GETG1 These are termed glue routines and their purpose is to provide a standard programming interface to the internal MERLIN data structures There are more glue routines a complete list is given in chapter 9 After writing the subroutine one must insert a call to it in one of the empty plug in subroutines provided in MERLIN For example SUBROUTINE PLUG1 CALL NEWSH END There are 50 empty subroutines PLUG1 PLUG50 that can be used to accommodate plug in modules Naturally the file containing SUBROUTINE PLUG1 has to be recompiled 7 3 Naming the plug in module Plug in modules are referenced through a symbolic name chosen by the user The name for the plug in module must be declared in the MERLIN configuration file using the PLUG configuration directive It can be up to 10 characters long and must be unique among all MERLIN commands and other plug in modules For the above example we chose the name NEWSH The corresponding entry in the configuration file should be PLUG 1 NEWSH The plug in can be invoked using the name NEWSH In addition all other MERLIN features such as command aliasing output redirection etc hold for the new plug in as well The new plug in is also recognized by the MCL compiler 7 4 Adding on line help The help texts for all non panel commands
145. value has been reached 6 3 9 AUTO Syntax classification PAC Purpose Invokes a multi algorithm based strategy The associated panel is listed in figure 6 11 The panel parameters are as follows NOC An approximate upper bound for the number of calls to the objective function TARGET Specifies a target value When the value of the objective function falls below this value the AUTO procedure terminates MAD Specifies whether the MERLIN Automatic Derivatives are to be used when approximating the gradient vector Allowed values are 60 Command description Keyword Description Allowed values NOC Number of calls Any int gt 1 NOP Number of points Any int gt 1 TARGET Target value Any real FILE File name Any string TYPE File type Text Bin CANCEL Cancel Proceed 0 1 CANCEL Figure 6 12 The ACCUM panel e ON The MERLIN Automatic Derivatives are to be used e OFF Use the current derivative mode This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS GCALLS INFO Number of function evaluations that were performed Number of evaluations of the gradient vector Result code Possible values are e 1 All function eva
146. will be issued The messages involve version of the program authors and e mail contact header_status can be either on or off HEADER on i e messages will be printed MERLIN only HEADER off 8 2 9 PRINTOUT Syntax Purpose Default Used by Examples PRINTOUT printout_level Specifies the amount of output that will be issued while MERLIN starts and until the MERLIN prompt is reached for the first time This setting also affects the output of the prologue command printout_level can be full half or no The three possible ar guments are analogous to the MERLIN commands FULLPRINT HALFPRINT and NOPRINT that change the printout mode after MERLIN has started PRINTOUT no suppresses all output With PRINTOUT half only error messages are issued PRINTOUT full allows all output to be printed If this directive is omitted PRINTOUT full is assumed MERLIN only PRINTOUT half 8 3 File related directives 8 3 1 PDESC_FILE Syntax Purpose Default Used by PDESC FILE filename Sets the name of the MERLIN panel description file to file name If this directive is omitted the name of the MERLIN panel description file defaults to PDESC MERLIN and MCL File related directives 107 Examples PDESC_FILE enhanced PDESC PDESC_FILE usr local merlin pdesc 8 3 2 MACRO_FILE Syntax Purpose Default Used by Examples MACRO FILE filename Sets the name of the MERLIN macro file to file_name If thi
147. wing installer macros are used in the MERLIN source code In addition TYPE MXPLUG and FC are used in the MCL source as well e TYPE Specifies the Fortran type for floating point variables It should be set to either REAL or DOUBLE PRECISION The installer will ask for the appropriate setting Note that both MERLIN and MCL must be installed in the same precision in order for the programs to correctly cooperate e MXV The maximum number of optimization parameters The setting of MXV determines the size of a few one dimensional arrays used as work space e MXT The maximum number of terms when the objective function is coded as a sum of squared terms The setting of MXT determines the size of a few one dimensional arrays used as work space If you do not intend to code the objective function as as sum of squares set MXT to 1 Configuration 9 e CONFIG e FC e MCLMEM e MCLBUF e MXPLUG Name of the MERLIN MCL configuration file Configuration is described in 2 3 and in chapter 8 The default name substituted by the installer is CONFIG Some systems use the first character of an output line as a terminal control character In order to use a terminal control character set FC to 1X The installer always sets FC to no control character The size of an array available as run time memory for an MCL program The array is of type REAL or DOUBLE PRECISION depending on the setting of TYPE If you do not intend to run
148. with LD gt N e HOW input Determines how the Hessian matrix is to be calculated Allowed values are HOW F or HOW f Use only function values to approximate the Hessian matrix elements HOW G or HOW g Use only gradient values to approximate the Hessian matrix elements This value should be used only if SUBROUTINE GRANAL is available HOW or HOW a Call the user supplied SUBROUTINE HANAL Parameter related glue routines 119 9 1 8 SUBROUTINE GETJAC Definition SUBROUTINE GETJAC FJ LD REAL FJ LD x INTEGER LD Purpose Returns the Jacobian matrix evaluated at the current point The current Jacobian mode as defined by the JNUMER or JANAL commands is used Arguments e FJ output The Jacobian matrix stored as ofi EE J i j an Matrix FJ should have at least M x N storage locations available e LD input The leading dimension of matrix FJ with LD gt M 9 1 9 SUBROUTINE GETMAR Definition SUBROUTINE GETMAR MF XL XU DIMENSION MF REAL XL XU x Purpose Returns the current upper and lower bounds for all minimization parameters Bounds are normally set by the LMARGIN and RMARGIN commands and reset by the LDEMARGIN and RDEMARGIN commands Each of the arrays MF XL and XR should have at least N storage locations available Arguments e MF output For each minimization parameter z MF 1 indicates whether an upper lower or both bounds have been set Po
149. ycle failures allowed The step enhancement factor The minimum acceptable function drop per cycle The maximum number of function calls that are allowed in the line search The line search termination criterion The search is terminated when the endpoints that bracket the minimum have a relative distance less than LSTOL This parameter controls if the intended procedure will be executed or canceled If any changes to any of the panel parameters have been entered they are recorded anyway e 1 is the default value and the process advances normally e 0 cancels the action initially intended The following parameters can be returned to MCL programs FCALLS ITERDONE INFO Number of function evaluations that were performed Number of Roll iterations that were performed Result code Possible values are e 1 Target value has been reached e2 All function evaluations have been used e 3 Too many cycle failures 6 3 2 SIMPLEX Syntax classification PAC Purpose Invokes the Simplex minimization algorithm The associated panel is listed in figure 6 4 The panel parameters are as follows NOC PRINT An approximate upper bound for the number of calls to the objective function Determines the amount of output from the minimization method Allowed values are e0 No printout at all e 1 Display lower function values as they are discovered Minimization related commands 47 Keyword Description Allowed values NO
150. zs to their current values A range denoted as index corresponds to variables Zindex through n Similarly a range denoted as index2 corresponds to variables x through Zindex 4 Shared parameter properties One can specify a symbol that refers to some property of the minimization parameters For example SHORTDIS F will output the fixed parameters only SHORTDIS 1 10 25 30 F will display the parameters x through x19 225 through x39 and of all the fixed variables The complete list of supported properties is shown in table 4 1 5 In addition if the negation symbol is set in front of an index specification the meaning of the specification is reversed For example a in front of an index or a name excludes the corresponding parameter Also a in front of a range excludes the parameters in that range and so on so forth A in front of an attribute specification excludes the parameters possessing this attribute Note that no spaces nor tabs are allowed in between the negation operator and the specification that follows Example GRADDIS F LDEMARGIN M Panels are based on the one line input and are used to display and change the input parameters for some of the MERLIN commands A panel displays in a tabular form all parameters that may be changed their corresponding keywords a short description of their function their default values and a list or range of allowed values A typical panel is shown in figure 4 1 The pane

Download Pdf Manuals

Related Search

Related Contents

Craftsman 88970 Snow Blower User Manual  Téléchargez ici le mode d`emploi du comparateur Assurances.be  Specification    SHARP SERVICE MANUAL - The Sharp MZ  Rentrée 2014 : des innovations pour tous les goûts  Swann PRO-640  DMI70 : Reference and Installation Manual  BEDIENUNGSANLEITUNG www.hobbico.de - mr  ventanas y puertas de madera pella garantía limitada  

Copyright © All rights reserved. Failed to retrieve file