doc/info/augmented_lagrangian.texi

   1 @menu
   2 * Functions and Variables for augmented_lagrangian::
   3 @end menu
   4
   5 @node Functions and Variables for augmented_lagrangian,  , Package augmented_lagrangian, Package augmented_lagrangian
   6 @section Functions and Variables for augmented_lagrangian
   7
   8 @anchor{augmented_lagrangian_method}
   9 @deffn  {Function} augmented_lagrangian_method @
  10 @fname{augmented_lagrangian_method} (@var{FOM}, @var{xx}, @var{C}, @var{yy}) @
  11 @fname{augmented_lagrangian_method} (@var{FOM}, @var{xx}, @var{C}, @var{yy}, optional_args) @
  12 @fname{augmented_lagrangian_method} ([@var{FOM}, @var{grad}], @var{xx}, @var{C}, @var{yy}) @
  13 @fname{augmented_lagrangian_method} ([@var{FOM}, @var{grad}], @var{xx}, @var{C}, @var{yy}, optional_args)
  14
  15 Returns an approximate minimum of the expression @var{FOM}
  16 with respect to the variables @var{xx},
  17 holding the constraints @var{C} equal to zero.
  18 @var{yy} is a list of initial guesses for @var{xx}.
  19 The method employed is the augmented Lagrangian method (see Refs [1] and [2]).
  20
  21 @var{grad}, if present, is the gradient of @var{FOM} with respect to @var{xx},
  22 represented as a list of expressions,
  23 one for each variable in @var{xx}.
  24 If not present, the gradient is constructed automatically.
  25
  26 @var{FOM} and each element of @var{grad}, if present,
  27 must be ordinary expressions, not names of functions or lambda expressions.
  28
  29 @code{optional_args} represents additional arguments,
  30 specified as @code{@var{symbol} = @var{value}}.
  31 The optional arguments recognized are:
  32
  33 @table @code
  34 @item niter
  35 Number of iterations of the augmented Lagrangian algorithm
  36 @item lbfgs_tolerance
  37 Tolerance supplied to LBFGS
  38 @item iprint
  39 IPRINT parameter (a list of two integers which controls verbosity) supplied to LBFGS
  40 @item %lambda
  41 Initial value of @code{%lambda} to be used for calculating the augmented Lagrangian
  42 @end table
  43
  44 This implementation minimizes the augmented Lagrangian by
  45 applying the limited-memory BFGS (LBFGS) algorithm,
  46 which is a quasi-Newton algorithm.
  47
  48 @code{load("augmented_lagrangian")} loads this function.
  49
  50 See also @ref{Package lbfgs}
  51
  52 References:
  53
  54 @c Both links seem invalid now (one redirects somewhere, one is access forbidden). Remove them?
  55 [1] @url{http://www-fp.mcs.anl.gov/otc/Guide/OptWeb/continuous/constrained/nonlinearcon/auglag.html}
  56
  57 [2] @url{http://www.cs.ubc.ca/spider/ascher/542/chap10.pdf}
  58
  59 Examples:
  60
  61 @c ===beg===
  62 @c load ("lbfgs");
  63 @c load ("augmented_lagrangian");
  64 @c FOM: x^2 + 2*y^2;
  65 @c xx: [x, y];
  66 @c C: [x + y - 1];
  67 @c yy: [1, 1];
  68 @c augmented_lagrangian_method(FOM, xx, C, yy, iprint=[-1,0]);
  69 @c ===end===
  70 @example
  71 @group
  72 (%i1) load ("lbfgs");
  73 (%o1)  /home/gunter/src/maxima-code/share/lbfgs/lbfgs.mac
  74 @end group
  75 @group
  76 (%i2) load ("augmented_lagrangian");
  77 (%o2) /home/gunter/src/maxima-code/share/contrib/augmented_lagra\
  78 ngian.mac
  79 @end group
  80 @group
  81 (%i3) FOM: x^2 + 2*y^2;
  82                                2    2
  83 (%o3)                       2 y  + x
  84 @end group
  85 @group
  86 (%i4) xx: [x, y];
  87 (%o4)                        [x, y]
  88 @end group
  89 @group
  90 (%i5) C: [x + y - 1];
  91 (%o5)                      [y + x - 1]
  92 @end group
  93 @group
  94 (%i6) yy: [1, 1];
  95 (%o6)                        [1, 1]
  96 @end group
  97 @group
  98 (%i7) augmented_lagrangian_method(FOM, xx, C, yy, iprint=[-1,0]);
  99 (%o7) [[x = 0.666659841080023, y = 0.333340272455448],
 100                                  %lambda = [- 1.333337940892518]]
 101 @end group
 102 @end example
 103
 104 Same example as before, but this time the gradient is supplied as an argument.
 105
 106 @c ===beg===
 107 @c load ("lbfgs")$
 108 @c load ("augmented_lagrangian")$
 109 @c FOM: x^2 + 2*y^2;
 110 @c xx: [x, y];
 111 @c grad : [2*x, 4*y];
 112 @c C: [x + y - 1];
 113 @c yy: [1, 1];
 114 @c augmented_lagrangian_method ([FOM, grad], xx, C, yy,
 115 @c                              iprint = [-1, 0]);
 116 @c ===end===
 117 @example
 118 (%i1) load ("lbfgs")$
 119 (%i2) load ("augmented_lagrangian")$
 120 @group
 121 (%i3) FOM: x^2 + 2*y^2;
 122                                2    2
 123 (%o3)                       2 y  + x
 124 @end group
 125 @group
 126 (%i4) xx: [x, y];
 127 (%o4)                        [x, y]
 128 @end group
 129 @group
 130 (%i5) grad : [2*x, 4*y];
 131 (%o5)                      [2 x, 4 y]
 132 @end group
 133 @group
 134 (%i6) C: [x + y - 1];
 135 (%o6)                      [y + x - 1]
 136 @end group
 137 @group
 138 (%i7) yy: [1, 1];
 139 (%o7)                        [1, 1]
 140 @end group
 141 @group
 142 (%i8) augmented_lagrangian_method ([FOM, grad], xx, C, yy,
 143                              iprint = [-1, 0]);
 144 (%o8) [[x = 0.6666598410800247, y = 0.3333402724554464],
 145                                  %lambda = [- 1.333337940892525]]
 146 @end group
 147 @end example
 148
 149 @opencatbox{Categories:}
 150 @category{Numerical methods}
 151 @category{Optimization}
 152 @category{Share packages}
 153 @category{Package augmented_lagrangian}
 154 @closecatbox
 155
 156 @end deffn
 157