diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 232 |
1 files changed, 232 insertions, 0 deletions
@@ -0,0 +1,232 @@ + +L-BFGS-B is released under the “New BSD License” (aka “Modified BSD License” or +“3-clause license”) +Please read attached file License.txt + + L-BFGS-B (version 3.0) march, 2011 + +This directory contains the modified/corrected limited memory +code for solving bound constrained optimization problems. + +_______________________________________________________________________ + + o f77 routines + + blas.f subset of blas + linpack.f subset of linpack + lbfgsb.f main routine + timer.f routine to compute CPU time + + o f77 and f90 drivers + + driver1.f driver1.f90 + driver2.f driver2.f90 + driver3.f driver3.f90 + + We recommend that the user read driver1.f/driver1.f90, which + give a good idea of how the code works + + o Makefile Linux/Unix users. + + To run the code on a Linux/Unix machine simply type + + make + + This will create the files + + x.lbfgsb_77_1 x.lbfgsb_90_1 + x.lbfgsb_77_2 x.lbfgsb_90_2 + x.lbfgsb_77_3 x.lbfgsb_90_3 + + which are the executable files for the drivers in the package. + One can execute the program by typing the name of the executable + file. + + o Output files are provided for each executable file in directory + OUPUTS + + output_77_1 output_90_1 + output_77_2 output_90_2 + output_77_3 output_90_3 + + o The following four articles are also included + + [1] algorithm.pdf - describes the algorithm + [2] compact.pdf - presents the compact form of matrices + [3] code.pdf - describes the code + [4] acm-remark.pdf - describes the modification/correction + + The most useful articles for those who only wish to use the code + are [3,4]. Users interested in understanding the algorithm should + read [1] and possibly also [2]. + +________________________________________________________________________ + +For questions and help contact + + Jorge Nocedal <nocedal@eecs.northwestern.edu> + Jose Luis Morales <jmorales@itam.mx> +________________________________________________________________________ + + + How to use L-BFGS-B + +************************************************************************ + + The simplest way to use the code is to modify one of the +drivers provided in the package. Most users will only need to make +a few changes to the drivers to run their applications. + + L-BFGS-B is written in FORTRAN 77, in double precision. The +user is required to calculate the function value f and its gradient g. +In order to allow the user complete control over these computations, +reverse communication is used. The routine setulb.f must be called +repeatedly under the control of the variable task. The calling +statement of L-BFGS-B is + + call setulb(n,m,x,l,u,nbd,f,g,factr,pgtol,wa,iwa,task,iprint, + + csave,lsave,isave,dsave) + + + Following is a description of all the parameters used in this call. + +c n is an INTEGER variable that must be set by the user to the +c number of variables. It is not altered by the routine. +c +c m is an INTEGER variable that must be set by the user to the +c number of corrections used in the limited memory matrix. +c It is not altered by the routine. Values of m < 3 are +c not recommended, and large values of m can result in excessive +c computing time. The range 3 <= m <= 20 is recommended. +c +c x is a DOUBLE PRECISION array of length n. On initial entry +c it must be set by the user to the values of the initial +c estimate of the solution vector. Upon successful exit, it +c contains the values of the variables at the best point +c found (usually an approximate solution). +c +c l is a DOUBLE PRECISION array of length n that must be set by +c the user to the values of the lower bounds on the variables. If +c the i-th variable has no lower bound, l(i) need not be defined. +c +c u is a DOUBLE PRECISION array of length n that must be set by +c the user to the values of the upper bounds on the variables. If +c the i-th variable has no upper bound, u(i) need not be defined. +c +c nbd is an INTEGER array of dimension n that must be set by the +c user to the type of bounds imposed on the variables: +c nbd(i)=0 if x(i) is unbounded, +c 1 if x(i) has only a lower bound, +c 2 if x(i) has both lower and upper bounds, +c 3 if x(i) has only an upper bound. +c +c f is a DOUBLE PRECISION variable. If the routine setulb returns +c with task(1:2)= 'FG', then f must be set by the user to +c contain the value of the function at the point x. +c +c g is a DOUBLE PRECISION array of length n. If the routine setulb +c returns with taskb(1:2)= 'FG', then g must be set by the user to +c contain the components of the gradient at the point x. +c +c factr is a DOUBLE PRECISION variable that must be set by the user. +c It is a tolerance in the termination test for the algorithm. +c The iteration will stop when +c +c (f^k - f^{k+1})/max{|f^k|,|f^{k+1}|,1} <= factr*epsmch +c +c where epsmch is the machine precision which is automatically +c generated by the code. Typical values for factr on a computer +c with 15 digits of accuracy in double precision are: +c factr=1.d+12 for low accuracy; +c 1.d+7 for moderate accuracy; +c 1.d+1 for extremely high accuracy. +c The user can suppress this termination test by setting factr=0. +c +c pgtol is a double precision variable. +c On entry pgtol >= 0 is specified by the user. The iteration +c will stop when +c +c max{|proj g_i | i = 1, ..., n} <= pgtol +c +c where pg_i is the ith component of the projected gradient. +c The user can suppress this termination test by setting pgtol=0. +c +c wa is a DOUBLE PRECISION array of length +c (2mmax + 5)nmax + 11mmax^2 + 8mmax used as workspace. +c This array must not be altered by the user. +c +c iwa is an INTEGER array of length 3nmax used as +c workspace. This array must not be altered by the user. +c +c task is a CHARACTER string of length 60. +c On first entry, it must be set to 'START'. +c On a return with task(1:2)='FG', the user must evaluate the +c function f and gradient g at the returned value of x. +c On a return with task(1:5)='NEW_X', an iteration of the +c algorithm has concluded, and f and g contain f(x) and g(x) +c respectively. The user can decide whether to continue or stop +c the iteration. +c When +c task(1:4)='CONV', the termination test in L-BFGS-B has been +c satisfied; +c task(1:4)='ABNO', the routine has terminated abnormally +c without being able to satisfy the termination conditions, +c x contains the best approximation found, +c f and g contain f(x) and g(x) respectively; +c task(1:5)='ERROR', the routine has detected an error in the +c input parameters; +c On exit with task = 'CONV', 'ABNO' or 'ERROR', the variable task +c contains additional information that the user can print. +c This array should not be altered unless the user wants to +c stop the run for some reason. See driver2 or driver3 +c for a detailed explanation on how to stop the run +c by assigning task(1:4)='STOP' in the driver. +c +c iprint is an INTEGER variable that must be set by the user. +c It controls the frequency and type of output generated: +c iprint<0 no output is generated; +c iprint=0 print only one line at the last iteration; +c 0<iprint<99 print also f and |proj g| every iprint iterations; +c iprint=99 print details of every iteration except n-vectors; +c iprint=100 print also the changes of active set and final x; +c iprint>100 print details of every iteration including x and g; +c When iprint > 0, the file iterate.dat will be created to +c summarize the iteration. +c +c csave is a CHARACTER working array of length 60. +c +c lsave is a LOGICAL working array of dimension 4. +c On exit with task = 'NEW_X', the following information is +c available: +c lsave(1) = .true. the initial x did not satisfy the bounds; +c lsave(2) = .true. the problem contains bounds; +c lsave(3) = .true. each variable has upper and lower bounds. +c +c isave is an INTEGER working array of dimension 44. +c On exit with task = 'NEW_X', it contains information that +c the user may want to access: +c isave(30) = the current iteration number; +c isave(34) = the total number of function and gradient +c evaluations; +c isave(36) = the number of function value or gradient +c evaluations in the current iteration; +c isave(38) = the number of free variables in the current +c iteration; +c isave(39) = the number of active constraints at the current +c iteration; +c +c see the subroutine setulb.f for a description of other +c information contained in isave +c +c dsave is a DOUBLE PRECISION working array of dimension 29. +c On exit with task = 'NEW_X', it contains information that +c the user may want to access: +c dsave(2) = the value of f at the previous iteration; +c dsave(5) = the machine precision epsmch generated by the code; +c dsave(13) = the infinity norm of the projected gradient; +c +c see the subroutine setulb.f for a description of other +c information contained in dsave +c +************************************************************************ + |