asamin   

  ASAMIN A gateway function to Adaptive Simulated Annealing (ASA)

  ASAMIN is a matlab gateway function to Lester Ingber's Adaptive
  Simulated Annealing (ASA)

  Copyright (c) 1999-2001  Shinichi Sakata. All Rights Reserved. 

  $Id: asamin.m,v 1.1.2.1 2004/03/27 14:41:06 michel Exp $

  Usage:

  asamin ('set')

    lists the current value of each option.

  asamin ('set', opt_name)

    shows the current value of the option given by a character string
    opt_name; e.g., 

        asamin ('set', 'seed')

  asamin ('set', opt_name, opt_value)

    set the value opt_value to the option opt_name; e.g.,

        asamin ('set', 'seed', 654342)
        asamin ('set', 'asa_out_file', 'example.log')

  The valid options in these commands are:

    rand_seed
    test_in_cost_func
    use_rejected_cost
    asa_out_file
    limit_acceptances
    limit_generated
    limit_invalid
    accepted_to_generated_ratio
    cost_precision
    maximum_cost_repeat
    number_cost_samples
    temperature_ratio_scale
    cost_parameter_scale
    temperature_anneal_scale
    include_integer_parameters
    user_initial_parameters
    sequential_parameters
    initial_parameter_temperature
    acceptance_frequency_modulus
    generated_frequency_modulus
    reanneal_cost
    reanneal_parameters
    delta_x

    rand_seed is the seed of the random number generation in ASA. 

    If test_in_cost_func is set to zero, the cost function should
    simply return the value of the objective function. When
    test_in_cost_func is set to one, asamin () calls the cost
    function with a threshold value as well as the parameter
    value. The cost function needs to judge if the value of the cost
    function exceeds the threshold as well as compute the value of
    the cost function when asamin () requires. (See COST FUNCTION
    below for details.)

    All other items but use_rejected_cost belong to structure
    USER_OPTIONS in ASA. See ASA_README in the ASA package for
    details. The default value of use_rejected_cost is zero. If you
    set this option to one, ASA uses the current cost value to
    compute certain indices, even if the current state is rejected by
    the user cost function, provided that the current cost value is
    lower than the cost value of the past best state. (See COST
    FUNCTION below about the user cost function.)

  asamin ('reset')
    resets all option values to the hard-coded default values.

  [fstar,xstar,grad,hessian,state] = ...
     asamin ('minimize', func, xinit, xmin, xmax, xtype,...
              parm1, parm2, ...)

     minimizes the cost function func (also see COST FUNCTION below).
     The argument xinit specifies the initial value of the arguments
     of the cost function. Each element of the vectors xmin and xmax
     specify the lower and upper bounds of the corresponding
     argument.  The vector xtype indicates the types of the
     arguments. If xtype(i) is -1 if the i'th argument is real;
     xtype(i) is 1 if the i'th argument is integer. If this argument
     should be ignored in reannealing, multiply the corresponding
     element of xtype by 2 so that the element is 2 or -2. All
     parameters following xtype are optional and simply passed to the
     cost function each time the cost function is called.

     This way of calling asamin returns the following values:

     fstar
       The value of the objective function at xstar.
     xstar
       The argument vector at the exit from the ASA routine. If things go
       well, xstar should be the minimizer of "func".
     grad
       The gradient of "func" at xstar.
     hessian
       The Hessian of "func" at xstar.
     state
       The vector containing the information on the exit state. 
       state(1) is the exit_code, and state(2) is the cost flag. See 
       ASA_README for details.


     
  COST FUNCTION

  If test_in_cost_func is set to zero, asamin () calls the "cost
  function" (say, cost_func) with one argument, say x (the real cost
  function is evaluated at this point). Cost_func is expected to
  return the value of the objective function and cost_flag, the
  latter of which must be zero if any constraint (if any) is
  violated; otherwise one.

  When test_in_cost_func is equal to one, asamin () calls the "cost
  function" (say, cost_func) with three arguments, say, x (at which
  the real cost function is evaluated), critical_cost_value, and
  no_test_flag. Asamin expects cost_func to return three scalar
  values, say, cost_value, cost_flag, and user_acceptance_flag in the
  following manner.
   
    1. The function cost_func first checks if x satisfies the
    constraints of the minimization problem. If any of the
    constraints is not satisfied, cost_func sets zero to cost_flag
    and return. (user_acceptance_flag and cost_value will not be used
    by asamin () in this case.) If all constraints are satisfied, set
    one to cost_flag, and proceed to the next step.
   
    2. If asamin () calls cost_func with no_test_flag==1, cost_func
    must compute the value of the cost function, set it to cost_value
    and return. When no_test_flag==0, cost_func is expected to judge
    if the value of the cost function is greater than
    critical_cost_value. If the value of the cost function is found
    greater than critical_cost_value, cost_func must set zero to
    user_acceptance_flag and return. (asamin () will not use
    cost_value in this case.) On the other hand, if the value of the
    cost function is found no greater than critical_cost_value,
    cost_func must compute the cost function at x, set it to
    cost_value, and set one to user_acceptance_flag.
   
  Remark: To understand the usefulness of test_in_cost_func == 1,
  note that it is sometimes easier to check if the value of the cost
  function is greater than critical_cost_value than compute the value
  of the cost function. For example, suppose that the cost function g
  is implicitly defined by an equation f(g(x),x)=0, where f is
  strictly increasing in the first argument, and evaluation of g(x)
  is computationally expensive (e.g., requiring an iterative method
  to find a solution to f(y,x)=0). But we can easily show that
  f(critical_cost_value,x) < 0 if and only if g(x) >
  critical_cost_value. We can judge if g(x) > critical_cost_value by
  computing f(critical_cost_value,x). The value of g(x) is not
  necessary.

0001 %  ASAMIN A gateway function to Adaptive Simulated Annealing (ASA)
0002 %
0003 %  ASAMIN is a matlab gateway function to Lester Ingber's Adaptive
0004 %  Simulated Annealing (ASA)
0005 %
0006 %  Copyright (c) 1999-2001  Shinichi Sakata. All Rights Reserved.
0007 %
0008 %  $Id: asamin.m,v 1.1.2.1 2004/03/27 14:41:06 michel Exp $
0009 %
0010 %  Usage:
0011 %
0012 %  asamin ('set')
0013 %
0014 %    lists the current value of each option.
0015 %
0016 %  asamin ('set', opt_name)
0017 %
0018 %    shows the current value of the option given by a character string
0019 %    opt_name; e.g.,
0020 %
0021 %        asamin ('set', 'seed')
0022 %
0023 %  asamin ('set', opt_name, opt_value)
0024 %
0025 %    set the value opt_value to the option opt_name; e.g.,
0026 %
0027 %        asamin ('set', 'seed', 654342)
0028 %        asamin ('set', 'asa_out_file', 'example.log')
0029 %
0030 %  The valid options in these commands are:
0031 %
0032 %    rand_seed
0033 %    test_in_cost_func
0034 %    use_rejected_cost
0035 %    asa_out_file
0036 %    limit_acceptances
0037 %    limit_generated
0038 %    limit_invalid
0039 %    accepted_to_generated_ratio
0040 %    cost_precision
0041 %    maximum_cost_repeat
0042 %    number_cost_samples
0043 %    temperature_ratio_scale
0044 %    cost_parameter_scale
0045 %    temperature_anneal_scale
0046 %    include_integer_parameters
0047 %    user_initial_parameters
0048 %    sequential_parameters
0049 %    initial_parameter_temperature
0050 %    acceptance_frequency_modulus
0051 %    generated_frequency_modulus
0052 %    reanneal_cost
0053 %    reanneal_parameters
0054 %    delta_x
0055 %
0056 %    rand_seed is the seed of the random number generation in ASA.
0057 %
0058 %    If test_in_cost_func is set to zero, the cost function should
0059 %    simply return the value of the objective function. When
0060 %    test_in_cost_func is set to one, asamin () calls the cost
0061 %    function with a threshold value as well as the parameter
0062 %    value. The cost function needs to judge if the value of the cost
0063 %    function exceeds the threshold as well as compute the value of
0064 %    the cost function when asamin () requires. (See COST FUNCTION
0065 %    below for details.)
0066 %
0067 %    All other items but use_rejected_cost belong to structure
0068 %    USER_OPTIONS in ASA. See ASA_README in the ASA package for
0069 %    details. The default value of use_rejected_cost is zero. If you
0070 %    set this option to one, ASA uses the current cost value to
0071 %    compute certain indices, even if the current state is rejected by
0072 %    the user cost function, provided that the current cost value is
0073 %    lower than the cost value of the past best state. (See COST
0074 %    FUNCTION below about the user cost function.)
0075 %
0076 %  asamin ('reset')
0077 %    resets all option values to the hard-coded default values.
0078 %
0079 %  [fstar,xstar,grad,hessian,state] = ...
0080 %     asamin ('minimize', func, xinit, xmin, xmax, xtype,...
0081 %              parm1, parm2, ...)
0082 %
0083 %     minimizes the cost function func (also see COST FUNCTION below).
0084 %     The argument xinit specifies the initial value of the arguments
0085 %     of the cost function. Each element of the vectors xmin and xmax
0086 %     specify the lower and upper bounds of the corresponding
0087 %     argument.  The vector xtype indicates the types of the
0088 %     arguments. If xtype(i) is -1 if the i'th argument is real;
0089 %     xtype(i) is 1 if the i'th argument is integer. If this argument
0090 %     should be ignored in reannealing, multiply the corresponding
0091 %     element of xtype by 2 so that the element is 2 or -2. All
0092 %     parameters following xtype are optional and simply passed to the
0093 %     cost function each time the cost function is called.
0094 %
0095 %     This way of calling asamin returns the following values:
0096 %
0097 %     fstar
0098 %       The value of the objective function at xstar.
0099 %     xstar
0100 %       The argument vector at the exit from the ASA routine. If things go
0101 %       well, xstar should be the minimizer of "func".
0102 %     grad
0103 %       The gradient of "func" at xstar.
0104 %     hessian
0105 %       The Hessian of "func" at xstar.
0106 %     state
0107 %       The vector containing the information on the exit state.
0108 %       state(1) is the exit_code, and state(2) is the cost flag. See
0109 %       ASA_README for details.
0110 %
0111 %
0112 %
0113 %  COST FUNCTION
0114 %
0115 %  If test_in_cost_func is set to zero, asamin () calls the "cost
0116 %  function" (say, cost_func) with one argument, say x (the real cost
0117 %  function is evaluated at this point). Cost_func is expected to
0118 %  return the value of the objective function and cost_flag, the
0119 %  latter of which must be zero if any constraint (if any) is
0120 %  violated; otherwise one.
0121 %
0122 %  When test_in_cost_func is equal to one, asamin () calls the "cost
0123 %  function" (say, cost_func) with three arguments, say, x (at which
0124 %  the real cost function is evaluated), critical_cost_value, and
0125 %  no_test_flag. Asamin expects cost_func to return three scalar
0126 %  values, say, cost_value, cost_flag, and user_acceptance_flag in the
0127 %  following manner.
0128 %
0129 %    1. The function cost_func first checks if x satisfies the
0130 %    constraints of the minimization problem. If any of the
0131 %    constraints is not satisfied, cost_func sets zero to cost_flag
0132 %    and return. (user_acceptance_flag and cost_value will not be used
0133 %    by asamin () in this case.) If all constraints are satisfied, set
0134 %    one to cost_flag, and proceed to the next step.
0135 %
0136 %    2. If asamin () calls cost_func with no_test_flag==1, cost_func
0137 %    must compute the value of the cost function, set it to cost_value
0138 %    and return. When no_test_flag==0, cost_func is expected to judge
0139 %    if the value of the cost function is greater than
0140 %    critical_cost_value. If the value of the cost function is found
0141 %    greater than critical_cost_value, cost_func must set zero to
0142 %    user_acceptance_flag and return. (asamin () will not use
0143 %    cost_value in this case.) On the other hand, if the value of the
0144 %    cost function is found no greater than critical_cost_value,
0145 %    cost_func must compute the cost function at x, set it to
0146 %    cost_value, and set one to user_acceptance_flag.
0147 %
0148 %  Remark: To understand the usefulness of test_in_cost_func == 1,
0149 %  note that it is sometimes easier to check if the value of the cost
0150 %  function is greater than critical_cost_value than compute the value
0151 %  of the cost function. For example, suppose that the cost function g
0152 %  is implicitly defined by an equation f(g(x),x)=0, where f is
0153 %  strictly increasing in the first argument, and evaluation of g(x)
0154 %  is computationally expensive (e.g., requiring an iterative method
0155 %  to find a solution to f(y,x)=0). But we can easily show that
0156 %  f(critical_cost_value,x) < 0 if and only if g(x) >
0157 %  critical_cost_value. We can judge if g(x) > critical_cost_value by
0158 %  computing f(critical_cost_value,x). The value of g(x) is not
0159 %  necessary.
0160 %