prompt.monte

29 - def __init__(self, relax):

30 # Help. 31 self.__relax_help__ = \ 32 """Class containing the functions for Monte Carlo and related simulations.""" 33 34 # Add the generic help string. 35 self.__relax_help__ = self.__relax_help__ + "\n" + help.relax_class_help 36 37 # Place relax in the class namespace. 38 self.__relax__ = relax

39 40

41 - def create_data(self, run=None, method='back_calc'):

42 """Function for creating simulation data. 43 44 Keyword Arguments 45 ~~~~~~~~~~~~~~~~~ 46 47 run: The name of the run. 48 49 method: The simulation method. 50 51 52 Description 53 ~~~~~~~~~~~ 54 55 The method argument can either be set to 'back_calc' or 'direct', the choice of which 56 determines the simulation type. If the values or parameters of a run are calculated rather 57 than minimised, this option will have no effect, hence 'back_calc' and 'direct' are 58 identical. 59 60 For error analysis, the method argument should be set to 'back_calc' which will result in 61 proper Monte Carlo simulations. The data used for each simulation is back calculated from 62 the minimised model parameters and is randomised using Gaussian noise where the standard 63 deviation is from the original error set. When the method is set to 'back_calc', this 64 function should only be called after the model or run is fully minimised. 65 66 The simulation type can be changed by setting the method argument to 'direct'. This will 67 result in simulations which cannot be used in error analysis and which are no longer Monte 68 Carlo simulations. However, these simulations are required for certain model selection 69 techniques (see the documentation for the model selection function for details), and can be 70 used for other purposes. Rather than the data being back calculated from the fitted model 71 parameters, the data is generated by taking the original data and randomising using Gaussian 72 noise with the standard deviations set to the original error set. 73 """ 74 75 # Function intro text. 76 if self.__relax__.interpreter.intro: 77 text = sys.ps3 + "monte_carlo.create_data(" 78 text = text + "run=" + `run` 79 text = text + ", method=" + `method` + ")" 80 print text 81 82 # The run argument. 83 if type(run) != str: 84 raise RelaxStrError, ('run', run) 85 86 # The method argument. 87 if type(method) != str: 88 raise RelaxStrError, ('method', method) 89 90 # Execute the functional code. 91 self.__relax__.generic.monte_carlo.create_data(run=run, method=method)

92 93

94 - def error_analysis(self, run=None, prune=0):

95 """Function for calculating parameter errors from the Monte Carlo simulations. 96 97 Keyword Arguments 98 ~~~~~~~~~~~~~~~~~ 99 100 run: The name of the run. 101 102 prune: The proportion of the simulations to prune for the calculation of parameter errors. 103 104 105 Description 106 ~~~~~~~~~~~ 107 108 Parameter errors are calculated as the standard deviation of the distribution of parameter 109 values. This function should never be used if parameter values are obtained by minimisation 110 and the simulation data are generated using the method 'direct'. The reason is because only 111 true Monte Carlo simulations can give the true parameter errors. 112 113 If the values or parameters of a run are calculated rather than minimised, the prune 114 argument must be set to zero. The value of this argument is proportional to the number of 115 simulations removed prior to error calculation. If prune is set to 0, all simulations are 116 used for calculating errors, whereas a value of 1 excludes all data. In almost all cases 117 prune must be set to zero, any value greater than zero will result in an underestimation of 118 the error values. If a value is supplied, the lower and upper tails of the distribution of 119 chi-squared values will be excluded from the error calculation. 120 """ 121 122 # Function intro text. 123 if self.__relax__.interpreter.intro: 124 text = sys.ps3 + "monte_carlo.error_analysis(" 125 text = text + "run=" + `run` 126 text = text + ", prune=" + `prune` + ")" 127 print text 128 129 # The run argument. 130 if type(run) != str: 131 raise RelaxStrError, ('run', run) 132 133 # The prune argument. 134 if type(prune) != int and type(prune) != float: 135 raise RelaxNumError, ('prune', prune) 136 137 # Execute the functional code. 138 self.__relax__.generic.monte_carlo.error_analysis(run=run, prune=prune)

139 140

141 - def initial_values(self, run=None):

142 """Function for setting the initial simulation parameter values. 143 144 Keyword Arguments 145 ~~~~~~~~~~~~~~~~~ 146 147 run: The name of the run. 148 149 150 Description 151 ~~~~~~~~~~~ 152 153 This function only effects runs where minimisation occurs and can therefore be skipped if 154 the values or parameters of a run are calculated rather than minimised. However, if 155 accidently run in this case, the results will be unaffected. It should only be called after 156 the model or run is fully minimised. Once called, the functions 'grid_search' and 157 'minimise' will only effect the simulations and not the model parameters. 158 159 The initial values of the parameters for each simulation is set to the minimised parameters 160 of the model. A grid search can be undertaken for each simulation instead, although this 161 is computationally expensive and unnecessary. The minimisation function should be executed 162 for a second time after running this function. 163 """ 164 165 # Function intro text. 166 if self.__relax__.interpreter.intro: 167 text = sys.ps3 + "monte_carlo.initial_values(" 168 text = text + "run=" + `run` + ")" 169 print text 170 171 # The run argument. 172 if type(run) != str: 173 raise RelaxStrError, ('run', run) 174 175 # Execute the functional code. 176 self.__relax__.generic.monte_carlo.initial_values(run=run)

177 178

179 - def off(self, run=None):

180 """Function for turning simulations off. 181 182 Keyword Arguments 183 ~~~~~~~~~~~~~~~~~ 184 185 run: The name of the run. 186 """ 187 188 # Function intro text. 189 if self.__relax__.interpreter.intro: 190 text = sys.ps3 + "monte_carlo.off(" 191 text = text + "run=" + `run` + ")" 192 print text 193 194 # The run argument. 195 if type(run) != str: 196 raise RelaxStrError, ('run', run) 197 198 # Execute the functional code. 199 self.__relax__.generic.monte_carlo.off(run=run)

200 201

202 - def on(self, run=None):

203 """Function for turning simulations on. 204 205 Keyword Arguments 206 ~~~~~~~~~~~~~~~~~ 207 208 run: The name of the run. 209 """ 210 211 # Function intro text. 212 if self.__relax__.interpreter.intro: 213 text = sys.ps3 + "monte_carlo.on(" 214 text = text + "run=" + `run` + ")" 215 print text 216 217 # The run argument. 218 if type(run) != str: 219 raise RelaxStrError, ('run', run) 220 221 # Execute the functional code. 222 self.__relax__.generic.monte_carlo.on(run=run)

223 224

225 - def setup(self, run=None, number=500):

226 """Function for setting up Monte Carlo simulations. 227 228 Keyword Arguments 229 ~~~~~~~~~~~~~~~~~ 230 231 run: The name of the run. 232 233 number: The number of Monte Carlo simulations. 234 235 236 Description 237 ~~~~~~~~~~~ 238 239 This function must be called prior to any of the other Monte Carlo functions. The effect is 240 that the number of simulations for the given run will be set and that simulations will be 241 turned on. 242 """ 243 244 # Function intro text. 245 if self.__relax__.interpreter.intro: 246 text = sys.ps3 + "monte_carlo.setup(" 247 text = text + "run=" + `run` 248 text = text + ", number=" + `number` + ")" 249 print text 250 251 # The run argument. 252 if type(run) != str: 253 raise RelaxStrError, ('run', run) 254 255 # The number of simulations. 256 if type(number) != int: 257 raise RelaxIntError, ('number', number) 258 259 # Execute the functional code. 260 self.__relax__.generic.monte_carlo.setup(run=run, number=number)

261 262 263 264 # Modify all docstrings. 265 ######################## 266 267 __description__ = """ 268 Monte Carlo Simulation Overview 269 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 270 271 For proper error analysis using Monte Carlo simulations, a sequence of function calls is 272 required for running the various simulation components. The steps necessary for 273 implementing Monte Carlo simulations are: 274 275 1. The measured data set together with the corresponding error set should be loaded into 276 relax. 277 278 2. Either minimisation is used to optimise the parameters of the chosen model, or a 279 calculation is run. 280 281 3. To initialise and turn on Monte Carlo simulations, the number of simulations, n, needs 282 to be set. 283 284 4. The simulation data needs to be created either by back calculation from the fully 285 minimised model parameters from step 2 or by direct calculation when values are calculated 286 rather than minimised. The error set is used to randomise each simulation data set by 287 assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo 288 simulation. 289 290 5. Prior to minimisation of the parameters of each simulation, initial parameter estimates 291 are required. These are taken as the optimised model parameters. An alternative is to use 292 a grid search for each simulation to generate initial estimates, however this is extremely 293 computationally expensive. For the case where values are calculated rather than minimised, 294 this step should be skipped (although the results will be unaffected if this is accidently 295 run). 296 297 6. Each simulation requires minimisation or calculation. The same techniques as used in 298 step 2, excluding the grid search when minimising, should be used for the simulations. 299 300 7. The model parameter errors are calculated from the distribution of simulation 301 parameters. 302 303 304 Monte Carlo simulations can be turned on or off using functions within this class. Once the 305 function for setting up simulations has been called, simulations will be turned on. The 306 effect of having simulations turned on is that the functions used for minimisation (grid 307 search, minimise, etc) or calculation will only affect the simulation parameters and not the 308 model parameters. By subsequently turning simulations off using the appropriate function, 309 the functions used in minimisation will affect the model parameters and not the simulation 310 parameters. 311 312 313 An example, for model-free analysis, which includes only the functions required for 314 implementing the above steps is: 315 316 relax> grid_search('m1', inc=11) # Step 2. 317 relax> minimise('newton', run='m1') # Step 2. 318 relax> monte_carlo.setup('m1', number=500) # Step 3. 319 relax> monte_carlo.create_data('m1', method='back_calc') # Step 4. 320 relax> monte_carlo.initial_values('m1') # Step 5. 321 relax> minimise('newton', run='m1') # Step 6. 322 relax> monte_carlo.error_analysis('m1') # Step 7. 323 324 An example for reduced spectral density mapping is: 325 326 relax> calc('600MHz') # Step 2. 327 relax> monte_carlo.setup('600MHz', number=500) # Step 3. 328 relax> monte_carlo.create_data('600MHz', method='back_calc') # Step 4. 329 relax> calc('600MHz') # Step 6. 330 relax> monte_carlo.error_analysis('600MHz') # Step 7. 331 """ 332 333 create_data.__doc__ = create_data.__doc__ + "\n\n" + __description__ 334 error_analysis.__doc__ = error_analysis.__doc__ + "\n\n" + __description__ 335 initial_values.__doc__ = initial_values.__doc__ + "\n\n" + __description__ 336 off.__doc__ = off.__doc__ + "\n\n" + __description__ 337 on.__doc__ = on.__doc__ + "\n\n" + __description__ 338 setup.__doc__ = setup.__doc__ + "\n\n" + __description__

Source Code for Module prompt.monte_carlo