prompt.minimisation

30 - def __init__(self, relax):

31 """Class containing the calc, grid, minimisation, and set functions.""" 32 33 self.relax = relax

34 35

36 - def calc(self, run=None, print_flag=1):

37 """Function for calculating the function value. 38 39 Keyword Arguments 40 ~~~~~~~~~~~~~~~~~ 41 42 run: The name of the run. 43 """ 44 45 # Function intro text. 46 if self.relax.interpreter.intro: 47 text = sys.ps3 + "calc(" 48 text = text + "run=" + `run` 49 text = text + ", print_flag=" + `print_flag` + ")" 50 print text 51 52 # The run argument. 53 if type(run) != str: 54 raise RelaxStrError, ('run', run) 55 56 # The print flag. 57 if type(print_flag) != int: 58 raise RelaxIntError, ('print flag', print_flag) 59 60 # Execute the functional code. 61 self.relax.generic.minimise.calc(run=run, print_flag=print_flag)

62 63

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

65 """The grid search function. 66 67 Keyword Arguments 68 ~~~~~~~~~~~~~~~~~ 69 70 run: The name of the run to apply the grid search to. 71 72 lower: An array of the lower bound parameter values for the grid search. The length of the 73 array should be equal to the number of parameters in the model. 74 75 upper: An array of the upper bound parameter values for the grid search. The length of the 76 array should be equal to the number of parameters in the model. 77 78 inc: The number of increments to search over. If a single integer is given then the number 79 of increments will be equal in all dimensions. Different numbers of increments in each 80 direction can be set if 'inc' is set to an array of integers of length equal to the number 81 of parameters. 82 83 constraints: A flag specifying whether the parameters should be constrained. The default 84 is to turn constraints on (constraints=1). 85 86 print_flag: The amount of information to print to screen. Zero corresponds to minimal 87 output while higher values increase the amount of output. The default value is 1. 88 """ 89 90 # Function intro text. 91 if self.relax.interpreter.intro: 92 text = sys.ps3 + "grid_search(" 93 text = text + "run=" + `run` 94 text = text + ", lower=" + `lower` 95 text = text + ", upper=" + `upper` 96 text = text + ", inc=" + `inc` 97 text = text + ", constraints=" + `constraints` 98 text = text + ", print_flag=" + `print_flag` + ")" 99 print text 100 101 # The run argument. 102 if type(run) != str: 103 raise RelaxStrError, ('run', run) 104 105 # The lower bounds. 106 if lower == None: 107 pass 108 elif type(lower) != list: 109 raise RelaxListError, ('lower bounds', lower) 110 else: 111 for i in xrange(len(lower)): 112 if type(lower[i]) != float and type(lower[i]) != int: 113 raise RelaxListNumError, ('lower bounds', lower) 114 115 # The upper bounds. 116 if upper == None: 117 pass 118 elif type(upper) != list: 119 raise RelaxListError, ('upper bounds', upper) 120 else: 121 for i in xrange(len(upper)): 122 if type(upper[i]) != float and type(upper[i]) != int: 123 raise RelaxListNumError, ('upper bounds', upper) 124 125 # The incrementation value. 126 if type(inc) == int: 127 pass 128 elif type(inc) == list: 129 for i in xrange(len(inc)): 130 if type(inc[i]) != int: 131 raise RelaxIntListIntError, ('incrementation value', inc) 132 else: 133 raise RelaxIntListIntError, ('incrementation value', inc) 134 135 # Constraint flag. 136 if type(constraints) != int or (constraints != 0 and constraints != 1): 137 raise RelaxBinError, ('constraint flag', constraints) 138 139 # The print flag. 140 if type(print_flag) != int: 141 raise RelaxIntError, ('print flag', print_flag) 142 143 # Execute the functional code. 144 self.relax.generic.minimise.grid_search(run=run, lower=lower, upper=upper, inc=inc, constraints=constraints, print_flag=print_flag)

145 146

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

148 """Minimisation function. 149 150 Arguments 151 ~~~~~~~~~ 152 153 The arguments, which should all be strings, specify the minimiser as well as its options. A 154 minimum of one argument is required. As this calls the function 'generic_minimise' the full 155 list of allowed arguments is shown below in the reproduced 'generic_minimise' docstring. 156 Ignore all sections except those labelled as minimisation algorithms and minimisation 157 options. Also do not select the Method of Multipliers constraint algorithm as this is used 158 in combination with the given minimisation algorithm if the keyword argument 'constraints' 159 is set to 1. The grid search algorithm should also not be selected as this is accessed 160 using the 'grid' function instead. The first argument passed will be set to the 161 minimisation algorithm while all other arguments will be set to the minimisation options. 162 163 Keyword arguments differ from normal arguments having the form 'keyword = value'. All 164 arguments must precede keyword arguments in python. For more information see the examples 165 section below or the python tutorial. 166 167 168 Keyword Arguments 169 ~~~~~~~~~~~~~~~~~ 170 171 run: The name of the run. 172 173 func_tol: The function tolerance. This is used to terminate minimisation once the function 174 value between iterations is less than the tolerance. The default value is 1e-25. 175 176 grad_tol: The gradient tolerance. Minimisation is terminated if the current gradient value 177 is less than the tolerance. The default value is None. 178 179 max_iterations: The maximum number of iterations. The default value is 1e7. 180 181 constraints: A flag specifying whether the parameters should be constrained. The default 182 is to turn constraints on (constraints=1). 183 184 scaling: The diagonal scaling flag. The default that scaling is on (scaling=1). 185 186 187 print_flag: The amount of information to print to screen. Zero corresponds to minimal 188 output while higher values increase the amount of output. The default value is 1. 189 190 191 Diagonal scaling 192 ~~~~~~~~~~~~~~~~ 193 194 Diagonal scaling is the transformation of parameter values such that each value has a 195 similar order of magnitude. Certain minimisation techniques, for example the trust region 196 methods, perform extremely poorly with badly scaled problems. In addition, methods which 197 are insensitive to scaling such as Newton minimisation may still benefit due to the 198 minimisation of round off errors. 199 200 In Model-free analysis for example, if S2 = 0.5, te = 200 ps, and Rex = 15 1/s at 600 MHz, 201 the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18]. Rex is divided by 202 (2 * pi * 600,000,000)**2 to make it field strength independent. The scaling vector for 203 this model may be something like [1.0, 1e-9, 1/(2 * pi * 6e8)**2]. By dividing the unscaled 204 parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0]. To 205 revert to the original unscaled parameter vector, the scaled parameter vector and scaling 206 vector are multiplied. 207 208 209 Examples 210 ~~~~~~~~ 211 212 To minimise the model-free run 'm4' using Newton minimisation together with the GMW81 213 Hessian modification algorithm, the More and Thuente line search algorithm, a function 214 tolerance of 1e-25, no gradient tolerance, a maximum of 10,000,000 iterations, constraints 215 turned on to limit parameter values, and have normal printout, type any combination of: 216 217 relax> minimise('newton', run='m4') 218 relax> minimise('Newton', run='m4') 219 relax> minimise('newton', 'gmw', run='m4') 220 relax> minimise('newton', 'mt', run='m4') 221 relax> minimise('newton', 'gmw', 'mt', run='m4') 222 relax> minimise('newton', 'mt', 'gmw', run='m4') 223 relax> minimise('newton', run='m4', func_tol=1e-25) 224 relax> minimise('newton', run='m4', func_tol=1e-25, grad_tol=None) 225 relax> minimise('newton', run='m4', max_iter=1e7) 226 relax> minimise('newton', run=name, constraints=1, max_iter=1e7) 227 relax> minimise('newton', run='m4', print_flag=1) 228 229 To minimise the model-free run 'm5' using constrained Simplex minimisation with a maximum of 230 5000 iterations, type: 231 232 relax> minimise('simplex', run='m5', constraints=1, max_iter=5000) 233 234 235 236 Note 237 ~~~~ 238 239 -------------------------------------------------------------------------------------------- 240 241 All the text which follows is a reproduction of the docstring of the generic_minimise 242 function. Only take note of the minimisation algorithms and minimisation options sections, 243 the other sections are not relevant for this function. The Grid search and Method of 244 Multipliers algorithms CANNOT be selected as minimisation algorithms for this function. 245 246 The section entitled Keyword Arguments is also completely inaccessible therefore please 247 ignore that text. 248 249 -------------------------------------------------------------------------------------------- 250 251 """ 252 253 # Function intro text is found at the end. 254 255 # Keyword: run. 256 if keywords.has_key('run'): 257 run = keywords['run'] 258 else: 259 run = None 260 261 # Keyword: func_tol. 262 if keywords.has_key('func_tol'): 263 func_tol = keywords['func_tol'] 264 else: 265 func_tol = 1e-25 266 267 # Keyword: grad_tol. 268 if keywords.has_key('grad_tol'): 269 grad_tol = keywords['grad_tol'] 270 else: 271 grad_tol = None 272 273 # Keyword: max_iterations. 274 if keywords.has_key('max_iterations'): 275 max_iterations = keywords['max_iterations'] 276 elif keywords.has_key('max_iter'): 277 max_iterations = keywords['max_iter'] 278 else: 279 max_iterations = 10000000 280 281 # Keyword: constraints. 282 if keywords.has_key('constraints'): 283 constraints = keywords['constraints'] 284 else: 285 constraints = 1 286 287 # Keyword: scaling. 288 if keywords.has_key('scaling'): 289 scaling = keywords['scaling'] 290 else: 291 scaling = 1 292 293 # Keyword: print_flag. 294 if keywords.has_key('print_flag'): 295 print_flag = keywords['print_flag'] 296 else: 297 print_flag = 1 298 299 # Function intro text. 300 if self.relax.interpreter.intro: 301 text = sys.ps3 + "minimise(" 302 text = text + "*args=" + `args` 303 text = text + ", run=" + `run` 304 text = text + ", func_tol=" + `func_tol` 305 text = text + ", max_iterations=" + `max_iterations` 306 text = text + ", constraints=" + `constraints` 307 text = text + ", scaling=" + `scaling` 308 text = text + ", print_flag=" + `print_flag` + ")" 309 print text 310 311 # Minimisation algorithm. 312 if len(args) == 0: 313 raise RelaxNoneError, 'minimisation algorithm' 314 elif type(args[0]) != str: 315 raise RelaxStrError, ('minimisation algorithm', args[0]) 316 min_algor = args[0] 317 318 # Minimisation options. 319 min_options = args[1:] 320 321 # Test for invalid keywords. 322 valid_keywords = ['run', 'func_tol', 'grad_tol', 'max_iter', 'max_iterations', 'constraints', 'scaling', 'print_flag'] 323 for key in keywords: 324 valid = 0 325 for valid_key in valid_keywords: 326 if key == valid_key: 327 valid = 1 328 if not valid: 329 raise RelaxError, "Unknown keyword argument " + `key` + "." 330 331 # The run keyword. 332 if run == None: 333 raise RelaxNoneError, 'run' 334 elif type(run) != str: 335 raise RelaxStrError, ('run', run) 336 337 # The function tolerance value. 338 if func_tol != None and type(func_tol) != int and type(func_tol) != float: 339 raise RelaxNoneNumError, ('function tolerance', func_tol) 340 341 # The gradient tolerance value. 342 if grad_tol != None and type(grad_tol) != int and type(grad_tol) != float: 343 raise RelaxNoneNumError, ('gradient tolerance', grad_tol) 344 345 # The maximum number of iterations. 346 if type(max_iterations) != int and type(max_iterations) != float: 347 raise RelaxNumError, ('maximum number of iterations', max_iterations) 348 349 # Constraint flag. 350 if type(constraints) != int or (constraints != 0 and constraints != 1): 351 raise RelaxBinError, ('constraint flag', constraints) 352 elif constraints == 1: 353 min_algor = 'Method of Multipliers' 354 min_options = args 355 356 # Scaling. 357 if type(scaling) != int or (scaling != 0 and scaling != 1): 358 raise RelaxBinError, ('scaling', scaling) 359 360 # Print flag. 361 if type(print_flag) != int: 362 raise RelaxIntError, ('print flag', print_flag) 363 364 # Execute the functional code. 365 self.relax.generic.minimise.minimise(run=run, min_algor=min_algor, min_options=min_options, func_tol=func_tol, grad_tol=grad_tol, max_iterations=max_iterations, constraints=constraints, scaling=scaling, print_flag=print_flag)

366 367 368 369 # Modify the docstring of the minimise method to include the docstring of the generic_minimise function in 'minimise.generic'. 370 ############################################################################################################################## 371 372 minimise.__doc__ = minimise.__doc__ + "\n " 373 374 # Add four spaces to the start of the generic minimise docstring lines to align with the minimise method docstring. 375 doc = split(generic_minimise.__doc__, sep='\n') 376 for i in xrange(len(doc)): 377 minimise.__doc__ = minimise.__doc__ + " " + doc[i] + "\n"

Source Code for Module prompt.minimisation