generic_fns.minimise

1 ############################################################################### 2 # # 3 # Copyright (C) 2003-2012 Edward d'Auvergne # 4 # # 5 # This file is part of the program relax. # 6 # # 7 # relax is free software; you can redistribute it and/or modify # 8 # it under the terms of the GNU General Public License as published by # 9 # the Free Software Foundation; either version 2 of the License, or # 10 # (at your option) any later version. # 11 # # 12 # relax is distributed in the hope that it will be useful, # 13 # but WITHOUT ANY WARRANTY; without even the implied warranty of # 14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # 15 # GNU General Public License for more details. # 16 # # 17 # You should have received a copy of the GNU General Public License # 18 # along with relax; if not, write to the Free Software # 19 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # 20 # # 21 ############################################################################### 22 23 # Module docstring. 24 """Module for model minimisation/optimisation.""" 25 26 # Python module imports. 27 from re import search 28 29 # relax module imports. 30 from generic_fns.mol_res_spin import return_spin, spin_loop 31 from generic_fns import pipes 32 from relax_errors import RelaxError 33 import specific_fns 34 from status import Status; status = Status() 35 36

37 -def calc(verbosity=1):

38 """Function for calculating the function value. 39 40 @param verbosity: The amount of information to print. The higher the value, the greater 41 the verbosity. 42 @type verbosity: int 43 """ 44 45 # Test if the current data pipe exists. 46 pipes.test() 47 48 # Specific calculate function setup. 49 calculate = specific_fns.setup.get_specific_fn('calculate', cdp.pipe_type) 50 overfit_deselect = specific_fns.setup.get_specific_fn('overfit_deselect', cdp.pipe_type) 51 52 # Deselect spins lacking data: 53 overfit_deselect() 54 55 # Monte Carlo simulation calculation. 56 if hasattr(cdp, 'sim_state') and cdp.sim_state == 1: 57 # Loop over the simulations. 58 for i in xrange(cdp.sim_number): 59 # Print out. 60 if verbosity: 61 print(("Simulation " + repr(i+1))) 62 63 # Status. 64 if status.current_analysis: 65 status.auto_analysis[status.current_analysis].mc_number = i 66 else: 67 status.mc_number = i 68 69 # Calculation. 70 calculate(verbosity=verbosity-1, sim_index=i) 71 72 # Unset the status. 73 if status.current_analysis: 74 status.auto_analysis[status.current_analysis].mc_number = None 75 else: 76 status.mc_number = None 77 78 # Minimisation. 79 else: 80 calculate(verbosity=verbosity)

81 82

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

84 """The grid search function. 85 86 @param lower: The lower bounds of the grid search which must be equal to the number of 87 parameters in the model. 88 @type lower: array of numbers 89 @param upper: The upper bounds of the grid search which must be equal to the number of 90 parameters in the model. 91 @type upper: array of numbers 92 @param inc: The increments for each dimension of the space for the grid search. The 93 number of elements in the array must equal to the number of parameters in 94 the model. 95 @type inc: array of int 96 @param constraints: If True, constraints are applied during the grid search (elinating parts of 97 the grid). If False, no constraints are used. 98 @type constraints: bool 99 @param verbosity: The amount of information to print. The higher the value, the greater 100 the verbosity. 101 @type verbosity: int 102 """ 103 104 # Test if the current data pipe exists. 105 pipes.test() 106 107 # Specific grid search function. 108 grid_search = specific_fns.setup.get_specific_fn('grid_search', cdp.pipe_type) 109 overfit_deselect = specific_fns.setup.get_specific_fn('overfit_deselect', cdp.pipe_type) 110 111 # Deselect spins lacking data: 112 overfit_deselect() 113 114 # Monte Carlo simulation grid search. 115 if hasattr(cdp, 'sim_state') and cdp.sim_state == 1: 116 # Loop over the simulations. 117 for i in xrange(cdp.sim_number): 118 # Print out. 119 if verbosity: 120 print(("Simulation " + repr(i+1))) 121 122 # Status. 123 if status.current_analysis: 124 status.auto_analysis[status.current_analysis].mc_number = i 125 else: 126 status.mc_number = i 127 128 # Optimisation. 129 grid_search(lower=lower, upper=upper, inc=inc, constraints=constraints, verbosity=verbosity-1, sim_index=i) 130 131 # Unset the status. 132 if status.current_analysis: 133 status.auto_analysis[status.current_analysis].mc_number = None 134 else: 135 status.mc_number = None 136 137 # Grid search. 138 else: 139 grid_search(lower=lower, upper=upper, inc=inc, constraints=constraints, verbosity=verbosity)

140 141

142 -def minimise(min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=True, scaling=True, verbosity=1, sim_index=None):

143 """Minimisation function. 144 145 @param min_algor: The minimisation algorithm to use. 146 @type min_algor: str 147 @param min_options: An array of options to be used by the minimisation algorithm. 148 @type min_options: array of str 149 @param func_tol: The function tolerance which, when reached, terminates optimisation. 150 Setting this to None turns of the check. 151 @type func_tol: None or float 152 @param grad_tol: The gradient tolerance which, when reached, terminates optimisation. 153 Setting this to None turns of the check. 154 @type grad_tol: None or float 155 @param max_iterations: The maximum number of iterations for the algorithm. 156 @type max_iterations: int 157 @param constraints: If True, constraints are used during optimisation. 158 @type constraints: bool 159 @param scaling: If True, diagonal scaling is enabled during optimisation to allow the 160 problem to be better conditioned. 161 @type scaling: bool 162 @param verbosity: The amount of information to print. The higher the value, the greater 163 the verbosity. 164 @type verbosity: int 165 @param sim_index: The index of the simulation to optimise. This should be None if normal 166 optimisation is desired. 167 @type sim_index: None or int 168 """ 169 170 # Test if the current data pipe exists. 171 pipes.test() 172 173 # Specific minimisation function. 174 minimise = specific_fns.setup.get_specific_fn('minimise', cdp.pipe_type) 175 overfit_deselect = specific_fns.setup.get_specific_fn('overfit_deselect', cdp.pipe_type) 176 177 # Deselect spins lacking data: 178 overfit_deselect() 179 180 # Single Monte Carlo simulation. 181 if sim_index != None: 182 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, sim_index=sim_index) 183 184 # Monte Carlo simulation minimisation. 185 elif hasattr(cdp, 'sim_state') and cdp.sim_state == 1: 186 for i in xrange(cdp.sim_number): 187 # Print out. 188 if verbosity: 189 print(("Simulation " + repr(i+1))) 190 191 # Status. 192 if status.current_analysis: 193 status.auto_analysis[status.current_analysis].mc_number = i 194 else: 195 status.mc_number = i 196 197 # Optimisation. 198 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-1, sim_index=i) 199 200 # Unset the status. 201 if status.current_analysis: 202 status.auto_analysis[status.current_analysis].mc_number = None 203 else: 204 status.mc_number = None 205 206 # Standard minimisation. 207 else: 208 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)

209 210

211 -def reset_min_stats(data_pipe=None, spin=None):

212 """Function for resetting the minimisation statistics. 213 214 @param data_pipe: The name of the data pipe to reset the minimisation statisics of. This 215 defaults to the current data pipe. 216 @type data_pipe: str 217 @param spin: The spin data container if spin specific data is to be reset. 218 @type spin: SpinContainer 219 """ 220 221 # The data pipe. 222 if data_pipe == None: 223 data_pipe = pipes.cdp_name() 224 225 # Get the data pipe. 226 dp = pipes.get_pipe(data_pipe) 227 228 229 # Global minimisation statistics. 230 ################################# 231 232 # Chi-squared. 233 if hasattr(dp, 'chi2'): 234 dp.chi2 = None 235 236 # Iteration count. 237 if hasattr(dp, 'iter'): 238 dp.iter = None 239 240 # Function count. 241 if hasattr(dp, 'f_count'): 242 dp.f_count = None 243 244 # Gradient count. 245 if hasattr(dp, 'g_count'): 246 dp.g_count = None 247 248 # Hessian count. 249 if hasattr(dp, 'h_count'): 250 dp.h_count = None 251 252 # Warning. 253 if hasattr(dp, 'warning'): 254 dp.warning = None 255 256 257 # Sequence specific minimisation statistics. 258 ############################################ 259 260 # Loop over all spins. 261 for spin in spin_loop(): 262 # Chi-squared. 263 if hasattr(spin, 'chi2'): 264 spin.chi2 = None 265 266 # Iteration count. 267 if hasattr(spin, 'iter'): 268 spin.iter = None 269 270 # Function count. 271 if hasattr(spin, 'f_count'): 272 spin.f_count = None 273 274 # Gradient count. 275 if hasattr(spin, 'g_count'): 276 spin.g_count = None 277 278 # Hessian count. 279 if hasattr(spin, 'h_count'): 280 spin.h_count = None 281 282 # Warning. 283 if hasattr(spin, 'warning'): 284 spin.warning = None

285 286

287 -def return_conversion_factor(stat_type):

288 """Dummy function for returning 1.0. 289 290 @param stat_type: The name of the statistic. This is unused! 291 @type stat_type: str 292 @return: A conversion factor of 1.0. 293 @rtype: float 294 """ 295 296 return 1.0

297 298 299 return_data_name_doc = ["Minimisation statistic data type string matching patterns", """ 300 ____________________________________________________________________________________________ 301 | | | | 302 | Data type | Object name | Patterns | 303 |________________________|______________|__________________________________________________| 304 | | | | 305 | Chi-squared statistic | 'chi2' | '^[Cc]hi2$' or '^[Cc]hi[-_ ][Ss]quare' | 306 | | | | 307 | Iteration count | 'iter' | '^[Ii]ter' | 308 | | | | 309 | Function call count | 'f_count' | '^[Ff].*[ -_][Cc]ount' | 310 | | | | 311 | Gradient call count | 'g_count' | '^[Gg].*[ -_][Cc]ount' | 312 | | | | 313 | Hessian call count | 'h_count' | '^[Hh].*[ -_][Cc]ount' | 314 |________________________|______________|__________________________________________________| 315 """] 316

317 -def return_data_name(name):

318 """Return a unique identifying string for the minimisation parameter. 319 320 @param name: The minimisation parameter. 321 @type name: str 322 @return: The unique parameter identifying string. 323 @rtype: str 324 """ 325 326 # Chi-squared. 327 if search('^[Cc]hi2$', name) or search('^[Cc]hi[-_ ][Ss]quare', name): 328 return 'chi2' 329 330 # Iteration count. 331 if search('^[Ii]ter', name): 332 return 'iter' 333 334 # Function call count. 335 if search('^[Ff].*[ -_][Cc]ount', name): 336 return 'f_count' 337 338 # Gradient call count. 339 if search('^[Gg].*[ -_][Cc]ount', name): 340 return 'g_count' 341 342 # Hessian call count. 343 if search('^[Hh].*[ -_][Cc]ount', name): 344 return 'h_count'

345 346

347 -def return_grace_string(stat_type):

348 """Function for returning the Grace string representing the data type for axis labelling. 349 350 @param stat_type: The name of the statistic to return the Grace string for. 351 @type stat_type: str 352 @return: The Grace string. 353 @rtype: str 354 """ 355 356 # Get the object name. 357 object_name = return_data_name(stat_type) 358 359 # Chi-squared. 360 if object_name == 'chi2': 361 grace_string = '\\xc\\S2' 362 363 # Iteration count. 364 elif object_name == 'iter': 365 grace_string = 'Iteration count' 366 367 # Function call count. 368 elif object_name == 'f_count': 369 grace_string = 'Function call count' 370 371 # Gradient call count. 372 elif object_name == 'g_count': 373 grace_string = 'Gradient call count' 374 375 # Hessian call count. 376 elif object_name == 'h_count': 377 grace_string = 'Hessian call count' 378 379 # Return the Grace string. 380 return grace_string

381 382

383 -def return_units(stat_type):

384 """Dummy function which returns None as the stats have no units. 385 386 @param stat_type: The name of the statistic. This is unused! 387 @type stat_type: str 388 @return: Nothing. 389 @rtype: None 390 """ 391 392 return None

393 394

395 -def return_value(spin=None, stat_type=None, sim=None):

396 """Function for returning the minimisation statistic corresponding to 'stat_type'. 397 398 @param spin: The spin data container if spin specific data is to be reset. 399 @type spin: SpinContainer 400 @param stat_type: The name of the statistic to return the value for. 401 @type stat_type: str 402 @param sim: The index of the simulation to return the value for. If None, then the 403 normal value is returned. 404 @type sim: None or int 405 """ 406 407 # Get the object name. 408 object_name = return_data_name(stat_type) 409 410 # The statistic type does not exist. 411 if not object_name: 412 raise RelaxError("The statistic type " + repr(stat_type) + " does not exist.") 413 414 # The simulation object name. 415 object_sim = object_name + '_sim' 416 417 # Get the global statistic. 418 if spin == None: 419 # Get the statistic. 420 if sim == None: 421 if hasattr(cdp, object_name): 422 stat = getattr(cdp, object_name) 423 else: 424 stat = None 425 426 # Get the simulation statistic. 427 else: 428 if hasattr(cdp, object_sim): 429 stat = getattr(cdp, object_sim)[sim] 430 else: 431 stat = None 432 433 # Residue specific statistic. 434 else: 435 # Get the statistic. 436 if sim == None: 437 if hasattr(spin, object_name): 438 stat = getattr(spin, object_name) 439 else: 440 stat = None 441 442 # Get the simulation statistic. 443 else: 444 if hasattr(spin, object_sim): 445 stat = getattr(spin, object_sim)[sim] 446 else: 447 stat = None 448 449 # Return the statistic (together with None to indicate that there are no errors associated with the statistic). 450 return stat, None

451 452 453 set_doc = """ 454 Minimisation statistic set details 455 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 456 457 This shouldn't really be executed by a user. 458 """ 459

460 -def set(val=None, error=None, param=None, scaling=None, spin_id=None):

461 """Set global or spin specific minimisation parameters. 462 463 @keyword val: The parameter values. 464 @type val: number 465 @keyword param: The parameter names. 466 @type param: str 467 @keyword scaling: Unused. 468 @type scaling: float 469 @keyword spin_id: The spin identification string. 470 @type spin_id: str 471 """ 472 473 # Get the parameter name. 474 param_name = return_data_name(param) 475 476 # Global minimisation stats. 477 if spin_id == None: 478 # Chi-squared. 479 if param_name == 'chi2': 480 cdp.chi2 = val 481 482 # Iteration count. 483 elif param_name == 'iter': 484 cdp.iter = val 485 486 # Function call count. 487 elif param_name == 'f_count': 488 cdp.f_count = val 489 490 # Gradient call count. 491 elif param_name == 'g_count': 492 cdp.g_count = val 493 494 # Hessian call count. 495 elif param_name == 'h_count': 496 cdp.h_count = val 497 498 # Residue specific minimisation. 499 else: 500 # Get the spin. 501 spin = return_spin(spin_id) 502 503 # Chi-squared. 504 if param_name == 'chi2': 505 spin.chi2 = val 506 507 # Iteration count. 508 elif param_name == 'iter': 509 spin.iter = val 510 511 # Function call count. 512 elif param_name == 'f_count': 513 spin.f_count = val 514 515 # Gradient call count. 516 elif param_name == 'g_count': 517 spin.g_count = val 518 519 # Hessian call count. 520 elif param_name == 'h_count': 521 spin.h_count = val

522

Source Code for Module generic_fns.minimise