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 Description 192 ~~~~~~~~~~~ 193 194 Diagonal scaling. 195 196 Diagonal scaling is the transformation of parameter values such that each value has a 197 similar order of magnitude. Certain minimisation techniques, for example the trust region 198 methods, perform extemely poorly with badly scaled problems. In addition, methods which are 199 insensitive to scaling such as Newton minimisation may still benefit due to the minimisation 200 of round off errors. 201 202 In Model-free analysis for example, if S2 = 0.5, te = 200 ps, and Rex = 15 1/s at 600 MHz, 203 the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18]. Rex is divided by 204 (2*pi*600,000,000)**2 to make it field strength independent. The scaling vector for this 205 model may be something like [1.0, 1e-9, 1/(2*pi*6*1e8)**2]. By dividing the unscaled 206 parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0]. To 207 revert to the original unscaled parameter vector, the scaled parameter vector and scaling 208 vector are multiplied. 209 210 211 Examples 212 ~~~~~~~~ 213 214 To minimise the model-free run 'm4' using Newton minimisation together with the GMW81 215 Hessian modification algorithm, the More and Thuente line search algorithm, a function 216 tolerance of 1e-25, no gradient tolerance, a maximum of 10,000,000 iterations, constraints 217 turned on to limit parameter values, and have normal printout, type any combination of: 218 219 relax> minimise('newton', run='m4') 220 relax> minimise('Newton', run='m4') 221 relax> minimise('newton', 'gmw', run='m4') 222 relax> minimise('newton', 'mt', run='m4') 223 relax> minimise('newton', 'gmw', 'mt', run='m4') 224 relax> minimise('newton', 'mt', 'gmw', run='m4') 225 relax> minimise('newton', run='m4', func_tol=1e-25) 226 relax> minimise('newton', run='m4', func_tol=1e-25, grad_tol=None) 227 relax> minimise('newton', run='m4', max_iter=1e7) 228 relax> minimise('newton', run=name, constraints=1, max_iter=1e7) 229 relax> minimise('newton', run='m4', print_flag=1) 230 231 To minimise the model-free run 'm5' using constrained Simplex minimisation with a maximum of 232 5000 iterations, type: 233 234 relax> minimise('simplex', run='m5', constraints=1, max_iter=5000) 235 236 237 238 ____________________________________________________________________________________________ 239 240 Reproduction of the docstring of the generic_minimise function. Only take note of the 241 minimisation algorithms and minimisation options sections, the other sections are not 242 relevant for this function. The Grid search and Method of Multipliers algorithms cannot be 243 selected as minimisation algorithms for this function. 244 ____________________________________________________________________________________________ 245 246 """ 247 248 # Function intro text is found at the end. 249 250 # Keyword: run. 251 if keywords.has_key('run'): 252 run = keywords['run'] 253 else: 254 run = None 255 256 # Keyword: func_tol. 257 if keywords.has_key('func_tol'): 258 func_tol = keywords['func_tol'] 259 else: 260 func_tol = 1e-25 261 262 # Keyword: grad_tol. 263 if keywords.has_key('grad_tol'): 264 grad_tol = keywords['grad_tol'] 265 else: 266 grad_tol = None 267 268 # Keyword: max_iterations. 269 if keywords.has_key('max_iterations'): 270 max_iterations = keywords['max_iterations'] 271 elif keywords.has_key('max_iter'): 272 max_iterations = keywords['max_iter'] 273 else: 274 max_iterations = 10000000 275 276 # Keyword: constraints. 277 if keywords.has_key('constraints'): 278 constraints = keywords['constraints'] 279 else: 280 constraints = 1 281 282 # Keyword: scaling. 283 if keywords.has_key('scaling'): 284 scaling = keywords['scaling'] 285 else: 286 scaling = 1 287 288 # Keyword: print_flag. 289 if keywords.has_key('print_flag'): 290 print_flag = keywords['print_flag'] 291 else: 292 print_flag = 1 293 294 # Function intro text. 295 if self.relax.interpreter.intro: 296 text = sys.ps3 + "minimise(" 297 text = text + "*args=" + `args` 298 text = text + ", run=" + `run` 299 text = text + ", func_tol=" + `func_tol` 300 text = text + ", max_iterations=" + `max_iterations` 301 text = text + ", constraints=" + `constraints` 302 text = text + ", scaling=" + `scaling` 303 text = text + ", print_flag=" + `print_flag` + ")" 304 print text 305 306 # Minimisation algorithm. 307 if len(args) == 0: 308 raise RelaxNoneError, 'minimisation algorithm' 309 elif type(args[0]) != str: 310 raise RelaxStrError, ('minimisation algorithm', args[0]) 311 min_algor = args[0] 312 313 # Minimisation options. 314 min_options = args[1:] 315 316 # Test for invalid keywords. 317 valid_keywords = ['run', 'func_tol', 'grad_tol', 'max_iter', 'max_iterations', 'constraints', 'scaling', 'print_flag'] 318 for key in keywords: 319 valid = 0 320 for valid_key in valid_keywords: 321 if key == valid_key: 322 valid = 1 323 if not valid: 324 raise RelaxError, "Unknown keyword argument " + `key` + "." 325 326 # The run keyword. 327 if run == None: 328 raise RelaxNoneError, 'run' 329 elif type(run) != str: 330 raise RelaxStrError, ('run', run) 331 332 # The function tolerance value. 333 if func_tol != None and type(func_tol) != int and type(func_tol) != float: 334 raise RelaxNoneNumError, ('function tolerance', func_tol) 335 336 # The gradient tolerance value. 337 if grad_tol != None and type(grad_tol) != int and type(grad_tol) != float: 338 raise RelaxNoneNumError, ('gradient tolerance', grad_tol) 339 340 # The maximum number of iterations. 341 if type(max_iterations) != int and type(max_iterations) != float: 342 raise RelaxNumError, ('maximum number of iterations', max_iterations) 343 344 # Constraint flag. 345 if type(constraints) != int or (constraints != 0 and constraints != 1): 346 raise RelaxBinError, ('constraint flag', constraints) 347 elif constraints == 1: 348 min_algor = 'Method of Multipliers' 349 min_options = args 350 351 # Scaling. 352 if type(scaling) != int or (scaling != 0 and scaling != 1): 353 raise RelaxBinError, ('scaling', scaling) 354 355 # Print flag. 356 if type(print_flag) != int: 357 raise RelaxIntError, ('print flag', print_flag) 358 359 # Execute the functional code. 360 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)

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

Source Code for Module prompt.minimisation