1Blurb::
2Turn on scaling for variables, responses, and constraints
3
4Description::
5
6Some optimization and calibration methods support scaling of
7continuous design variables, objective functions, calibration terms,
8and constraints.  This is activated with the \c scaling keyword.
9Discrete variable scaling is not supported.
10
11When scaling is enabled, variables, functions, gradients, Hessians,
12etc., are transformed such that the method iterates in scaled variable
13space, whereas evaluations of the computational model as specified in
14the interface are performed on the original problem scale.  Therefore
15using scaling does not require rewriting the interface to the
16simulation code.
17
18Scaling also requires the specification of additional keywords \c
19*scale_types and/or \c *scales in the \ref variables and \ref
20responses blocks.  When the \c scaling keyword is omitted from \ref
21method, these scaling type and value specifications are ignored in the
22variables and responses sections.
23
24This page describes the usage of all scaling related keywords.  The
25additional keywords come in pairs, one pair for each set of quantities
26(variables, primary responses, or constraints) to be scaled.
27\li a \c *scales keyword, which gives characteristic values (divisors)
28\li a \c *scale_types keyword, which determines how to use the
29  characteristic values
30
31The pair of keywords both take argument(s), and the length of the
32arguments can be either be one or equal to the number of quantities to
33be scaled (see details in \ref responses for lengths when field
34responses are active).  If one argument is given, it will apply to all
35quantities in the set. See the examples below.
36
37<b> Scale Types </b>
38
39There are three scale types:
40<ol>
41  <li> \c value - characteristic value scaling
42
43    The target quantity will be scaled (divided) by the specified characteristic value.
44  </li>
45  <li> \c auto - automatic scaling
46
47     First the quantity is scaled by any characteristic value, then
48     automatic scaling will be attempted according to the following scheme:
49
50    <ul>
51      <li> two-sided bounds scaled into the interval [0,1];
52      <li> one-sided bound or targets are scaled by the characteristic
53         value, moving the bound or target to 1 and changing the sense of
54         inequalities where necessary;
55      <li> no bounds or targets: no automatic scaling possible, therefore no
56           scaling for this component
57    </ul>
58
59     Automatic scaling is not available for objective functions nor calibration
60     terms since they lack bound constraints. Futher, when automatically
61     scaled, linear constraints are scaled by characteristic values only, not
62     affinely scaled into [0,1].
63  <li> \c log - logarithmic scaling
64
65     First, any characteristic values from the
66     optional \c *_scales specification are applied. Then logarithm base
67     10 scaling is applied.
68
69     Logarithmic scaling is not available for
70     linear constraints.
71
72     When continuous design variables are log
73     scaled, linear constraints are not allowed.
74  </li>
75</ol>
76
77
78<b> Scales </b>
79
80The \c *scales keywords are used to specify the characteristic values.
81These must be non-zero real numbers. The numbers are used according to
82the corresponding \c *scale_types, as described above. A value of 1.0
83can be used to selectively omit some quantities in a vector from being
84scaled.
85
86Depending on the scale type, the characteristic values may be required or
87optional.
88\li \c auto, \c log - optional
89\li \c value - required.
90
91A warning is issued if scaling would result in division by a value
92smaller in magnitude than <tt>1.0e10*DBL_MIN</tt>.  User-provided
93values violating this lower bound are accepted unaltered, whereas for
94automatically calculated scaling, the lower bound is enforced.
95
96Topics::	method_independent_controls
97Examples::
98The two examples below are equivalent:
99\verbatim
100  responses
101    objective_functions 3
102    sense "maximize"
103    primary_scale_types = "value"
104    primary_scales = 1 1 100
105\endverbatim
106
107\verbatim
108  responses
109    objective_functions 3
110    sense "maximize"
111    primary_scale_types = "value" "value" "value"
112    primary_scales = 1 1 100
113\endverbatim
114
115Theory::
116Faq::
117See_Also::
118