prompt.minimisation

39 """Class containing the calc, grid, minimisation, and set functions.""" 40

41 - def calc(self, verbosity=1):

42 """Function for calculating the function value. 43 44 Keyword Arguments 45 ~~~~~~~~~~~~~~~~~ 46 47 verbosity: The amount of information to print to screen. Zero corresponds to minimal 48 output while higher values increase the amount of output. The default value is 1. 49 """ 50 51 # Function intro text. 52 if self._exec_info.intro: 53 text = self._exec_info.ps3 + "calc(" 54 text = text + "verbosity=" + repr(verbosity) + ")" 55 print(text) 56 57 # The argument checks. 58 arg_check.is_int(verbosity, 'verbosity level') 59 60 # Execute the functional code. 61 minimise.calc(verbosity=verbosity)

62 63

64 - def grid_search(self, lower=None, upper=None, inc=21, constraints=True, verbosity=1):

65 """The grid search function. 66 67 Keyword Arguments 68 ~~~~~~~~~~~~~~~~~ 69 70 lower: An array of the lower bound parameter values for the grid search. The length of the 71 array should be equal to the number of parameters in the model. 72 73 upper: An array of the upper bound parameter values for the grid search. The length of the 74 array should be equal to the number of parameters in the model. 75 76 inc: The number of increments to search over. If a single integer is given then the number 77 of increments will be equal in all dimensions. Different numbers of increments in each 78 direction can be set if 'inc' is set to an array of integers of length equal to the number 79 of parameters. 80 81 constraints: A boolean flag specifying whether the parameters should be constrained. The 82 default is to turn constraints on (constraints=True). 83 84 verbosity: The amount of information to print to screen. Zero corresponds to minimal 85 output while higher values increase the amount of output. The default value is 1. 86 """ 87 88 # Function intro text. 89 if self._exec_info.intro: 90 text = self._exec_info.ps3 + "grid_search(" 91 text = text + "lower=" + repr(lower) 92 text = text + ", upper=" + repr(upper) 93 text = text + ", inc=" + repr(inc) 94 text = text + ", constraints=" + repr(constraints) 95 text = text + ", verbosity=" + repr(verbosity) + ")" 96 print(text) 97 98 # The argument checks. 99 arg_check.is_num_list(lower, 'lower bounds', can_be_none=True) 100 arg_check.is_num_list(upper, 'upper bounds', can_be_none=True) 101 arg_check.is_int_or_int_list(inc, 'incrementation value', none_elements=True) 102 arg_check.is_bool(constraints, 'constraints flag') 103 arg_check.is_int(verbosity, 'verbosity level') 104 105 # Execute the functional code. 106 minimise.grid_search(lower=lower, upper=upper, inc=inc, constraints=constraints, verbosity=verbosity)

107 108

109 - def minimise(self, *args, **keywords):

110 """Minimisation function. 111 112 Arguments 113 ~~~~~~~~~ 114 115 The arguments, which should all be strings, specify the minimiser as well as its options. A 116 minimum of one argument is required. As this calls the minfx function 'generic_minimise' 117 the full list of allowed arguments is shown below in the reproduced 'generic_minimise' 118 docstring. Ignore all sections except those labelled as minimisation algorithms and 119 minimisation options. Also do not select the Method of Multipliers constraint algorithm as 120 this is used in combination with the given minimisation algorithm if the keyword argument 121 'constraints' is set to 1. The grid search algorithm should also not be selected as this is 122 accessed using the 'grid' function instead. The first argument passed will be set to the 123 minimisation algorithm while all other arguments will be set to the minimisation options. 124 125 Keyword arguments differ from normal arguments having the form 'keyword = value'. All 126 arguments must precede keyword arguments in python. For more information see the examples 127 section below or the python tutorial. 128 129 130 Keyword Arguments 131 ~~~~~~~~~~~~~~~~~ 132 133 func_tol: The function tolerance. This is used to terminate minimisation once the function 134 value between iterations is less than the tolerance. The default value is 1e-25. 135 136 grad_tol: The gradient tolerance. Minimisation is terminated if the current gradient value 137 is less than the tolerance. The default value is None. 138 139 max_iterations: The maximum number of iterations. The default value is 1e7. 140 141 constraints: A boolean flag specifying whether the parameters should be constrained. The 142 default is to turn constraints on (constraints=True). 143 144 scaling: The diagonal scaling boolean flag. The default that scaling is on (scaling=True). 145 146 verbosity: The amount of information to print to screen. Zero corresponds to minimal 147 output while higher values increase the amount of output. The default value is 1. 148 149 150 Diagonal scaling 151 ~~~~~~~~~~~~~~~~ 152 153 Diagonal scaling is the transformation of parameter values such that each value has a 154 similar order of magnitude. Certain minimisation techniques, for example the trust region 155 methods, perform extremely poorly with badly scaled problems. In addition, methods which 156 are insensitive to scaling such as Newton minimisation may still benefit due to the 157 minimisation of round off errors. 158 159 In Model-free analysis for example, if S2 = 0.5, te = 200 ps, and Rex = 15 1/s at 600 MHz, 160 the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18]. Rex is divided by 161 (2 * pi * 600,000,000)**2 to make it field strength independent. The scaling vector for 162 this model may be something like [1.0, 1e-9, 1/(2 * pi * 6e8)**2]. By dividing the unscaled 163 parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0]. To 164 revert to the original unscaled parameter vector, the scaled parameter vector and scaling 165 vector are multiplied. 166 167 168 Examples 169 ~~~~~~~~ 170 171 To apply Newton minimisation together with the GMW81 Hessian modification algorithm, the 172 More and Thuente line search algorithm, a function tolerance of 1e-25, no gradient 173 tolerance, a maximum of 10,000,000 iterations, constraints turned on to limit parameter 174 values, and have normal printout, type any combination of: 175 176 relax> minimise('newton') 177 relax> minimise('Newton') 178 relax> minimise('newton', 'gmw') 179 relax> minimise('newton', 'mt') 180 relax> minimise('newton', 'gmw', 'mt') 181 relax> minimise('newton', 'mt', 'gmw') 182 relax> minimise('newton', func_tol=1e-25) 183 relax> minimise('newton', func_tol=1e-25, grad_tol=None) 184 relax> minimise('newton', max_iter=1e7) 185 relax> minimise('newton', constraints=True, max_iter=1e7) 186 relax> minimise('newton', verbosity=1) 187 188 To use constrained Simplex minimisation with a maximum of 5000 iterations, type: 189 190 relax> minimise('simplex', constraints=True, max_iter=5000) 191 192 193 194 Note 195 ~~~~ 196 197 All the text which follows is a reproduction of the docstring of the generic_minimise 198 function from the minfx python package. Only take note of the minimisation algorithms and 199 minimisation options sections, the other sections are not relevant for this function. The 200 Grid search and Method of Multipliers algorithms CANNOT be selected as minimisation 201 algorithms for this function. 202 203 The section entitled Keyword Arguments is also completely inaccessible therefore please 204 ignore that text. 205 206 """ 207 208 # The function intro text is found at the end! 209 210 # Keyword: func_tol. 211 if 'func_tol' in keywords: 212 func_tol = keywords['func_tol'] 213 else: 214 func_tol = 1e-25 215 216 # Keyword: grad_tol. 217 if 'grad_tol' in keywords: 218 grad_tol = keywords['grad_tol'] 219 else: 220 grad_tol = None 221 222 # Keyword: max_iterations. 223 if 'max_iterations' in keywords: 224 max_iterations = keywords['max_iterations'] 225 elif 'max_iter' in keywords: 226 max_iterations = keywords['max_iter'] 227 else: 228 max_iterations = 10000000 229 230 # Keyword: constraints. 231 if 'constraints' in keywords: 232 constraints = keywords['constraints'] 233 else: 234 constraints = True 235 236 # Keyword: scaling. 237 if 'scaling' in keywords: 238 scaling = keywords['scaling'] 239 else: 240 scaling = True 241 242 # Keyword: verbosity. 243 if 'verbosity' in keywords: 244 verbosity = keywords['verbosity'] 245 else: 246 verbosity = 1 247 248 # Function intro text. 249 if self._exec_info.intro: 250 text = self._exec_info.ps3 + "minimise(" 251 text = text + "*args=" + repr(args) 252 text = text + ", func_tol=" + repr(func_tol) 253 text = text + ", max_iterations=" + repr(max_iterations) 254 text = text + ", constraints=" + repr(constraints) 255 text = text + ", scaling=" + repr(scaling) 256 text = text + ", verbosity=" + repr(verbosity) + ")" 257 print(text) 258 259 # Minimisation algorithm. 260 if len(args) == 0: 261 raise RelaxNoneError('minimisation algorithm') 262 for i in xrange(len(args)): 263 if not isinstance(args[i], str): 264 raise RelaxStrError('minimisation algorithm', args[0]) 265 min_algor = args[0] 266 267 # Minimisation options. 268 min_options = args[1:] 269 270 # Test for invalid keywords. 271 valid_keywords = ['func_tol', 'grad_tol', 'max_iter', 'max_iterations', 'constraints', 'scaling', 'verbosity'] 272 for key in keywords: 273 valid = False 274 for valid_key in valid_keywords: 275 if key == valid_key: 276 valid = True 277 if not valid: 278 raise RelaxError("Unknown keyword argument " + repr(key) + ".") 279 280 # The argument checks. 281 arg_check.is_num(func_tol, 'function tolerance') 282 arg_check.is_num(grad_tol, 'gradient tolerance', can_be_none=True) 283 arg_check.is_int(max_iterations, 'maximum number of iterations') 284 arg_check.is_bool(constraints, 'constraints flag') 285 arg_check.is_bool(scaling, 'diagonal scaling flag') 286 arg_check.is_int(verbosity, 'verbosity level') 287 288 # Constraint flag. 289 if constraints: 290 min_algor = 'Method of Multipliers' 291 min_options = args 292 293 # Execute the functional code. 294 minimise.minimise(min_algor=min_algor, min_options=min_options, func_tol=func_tol, grad_tol=grad_tol, max_iterations=max_iterations, constraints=constraints, scaling=scaling, verbosity=verbosity)

295 296 297 298 # Modify the docstring of the minimise method to include the docstring of the generic_minimise function in 'minimise.generic'. 299 ############################################################################################################################## 300 301 minimise.__doc__ = minimise.__doc__ + "\n " 302 303 # Add four spaces to the start of the generic minimise docstring lines to align with the minimise method docstring. 304 doc = split(generic_minimise.__doc__, sep='\n') 305 for i in xrange(len(doc)): 306 minimise.__doc__ = minimise.__doc__ + " " + doc[i] + "\n"

Source Code for Module prompt.minimisation