Class Mf_minimise

Class containing functions specific to model-free optimisation.

Instance Methods

_disassemble_param_vector(self, model_type, param_vector=None, spin=None, spin_id=None, sim_index=None)
Disassemble the model-free parameter vector.

_disassemble_result(self, param_vector=None, func=None, iter=None, fc=None, gc=None, hc=None, warning=None, spin=None, sim_index=None, model_type=None, scaling=None, scaling_matrix=None)
Disassemble the optimisation results.

_grid_search_config(self, num_params, spin=None, spin_id=None, lower=None, upper=None, inc=None, scaling_matrix=None, verbosity=1)
Configure the grid search.

_grid_search_diff_bounds(self, lower, upper)
Set up the default grid search bounds the diffusion tensor.

_grid_search_spin_bounds(self, spin, lower, upper)
Set up the default grid search bounds for a single spin.

_linear_constraints(self, num_params, model_type=None, spin=None, spin_id=None, scaling_matrix=None)
Set up the model-free linear constraint matrices A and b.

tuple _minimise_data_setup(self, data_store, min_algor, num_data_sets, min_options, spin=None, sim_index=None)
Set up all the data required for minimisation.

tuple _relax_data_opt_structs(self, spin, sim_index=None)
Package the relaxation data into the data structures used for optimisation.

_reset_min_stats(self)
Reset all the minimisation statistics.

calculate(self, spin_id=None, verbosity=1, sim_index=None)
Calculation of the model-free chi-squared value.

grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None)
The model-free grid search function.

minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling=True, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)
Model-free minimisation function.

Method Details

_disassemble_param_vector(self, model_type, param_vector=None, spin=None, spin_id=None, sim_index=None)

Disassemble the model-free parameter vector.

Parameters:

• model_type (str) - The model-free model type. This must be one of 'mf', 'local_tm', 'diff', or 'all'.
• param_vector (numpy array) - The model-free parameter vector.
• spin (SpinContainer instance) - The spin data container. If this argument is supplied, then the spin_id argument will be ignored.
• spin_id (str) - The spin identification string.
• sim_index (int) - The optional MC simulation index.

_disassemble_result(self, param_vector=None, func=None, iter=None, fc=None, gc=None, hc=None, warning=None, spin=None, sim_index=None, model_type=None, scaling=None, scaling_matrix=None)

Disassemble the optimisation results.

Parameters:

• param_vector (numpy array) - The model-free parameter vector.
• func (float) - The optimised chi-squared value.
• iter (int) - The number of optimisation steps required to find the minimum.
• fc (int) - The function count.
• gc (int) - The gradient count.
• hc (int) - The Hessian count.
• warning (str or None) - Any optimisation warnings.
• spin (SpinContainer instance or None) - The spin container.
• sim_index (int or None) - The Monte Carlo simulation index.
• model_type (str) - The model-free model type, one of 'mf', 'local_tm', 'diff', or 'all'.
• scaling (bool) - If True, diagonal scaling is enabled during optimisation to allow the problem to be better conditioned.
• scaling_matrix (numpy diagonal matrix) - The diagonal, square scaling matrix.

_grid_search_config(self, num_params, spin=None, spin_id=None, lower=None, upper=None, inc=None, scaling_matrix=None, verbosity=1)

Configure the grid search.

Parameters:

• num_params (int) - The number of parameters in the model.
• spin (SpinContainer instance) - The spin data container.
• spin_id (str) - The spin identification string.
• lower (array of numbers) - The lower bounds of the grid search which must be equal to the number of parameters in the model.
• upper (array of numbers) - The upper bounds of the grid search which must be equal to the number of parameters in the model.
• inc (array of int) - The increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model.
• scaling_matrix (numpy diagonal matrix) - The diagonal, square scaling matrix.
• verbosity (int) - A flag specifying the amount of information to print. The higher the value, the greater the verbosity.

_grid_search_diff_bounds(self, lower, upper)

Set up the default grid search bounds the diffusion tensor.

This method appends the default bounds to the lower and upper lists.

Parameters:

• lower (list) - The lower bound list to append to.
• upper (list) - The upper bound list to append to.

_grid_search_spin_bounds(self, spin, lower, upper)

Set up the default grid search bounds for a single spin.

This method appends the default bounds to the lower and upper lists. The ordering of the lists in min_options matches that of the params list in the spin container.

Parameters:

• spin (class instance) - A SpinContainer object.
• lower (list) - The lower bound list to append to.
• upper (list) - The upper bound list to append to.

_linear_constraints(self, num_params, model_type=None, spin=None, spin_id=None, scaling_matrix=None)

Set up the model-free linear constraint matrices A and b.

Standard notation

The order parameter constraints are:

   0 <= S2 <= 1
   0 <= S2f <= 1
   0 <= S2s <= 1

By substituting the formula S2 = S2f.S2s into the above inequalities, the additional two inequalities can be derived:

   S2 <= S2f
   S2 <= S2s

Correlation time constraints are:

   te >= 0
   tf >= 0
   ts >= 0

   tf <= ts

   te, tf, ts <= 2 * tm

Additional constraints used include:

   Rex >= 0
   0.9e-10 <= r <= 2e-10
   -300e-6 <= CSA <= 0

Rearranged notation

The above inequality constraints can be rearranged into:

   S2 >= 0
   -S2 >= -1
   S2f >= 0
   -S2f >= -1
   S2s >= 0
   -S2s >= -1
   S2f - S2 >= 0
   S2s - S2 >= 0
   te >= 0
   tf >= 0
   ts >= 0
   ts - tf >= 0
   Rex >= 0
   r >= 0.9e-10
   -r >= -2e-10
   CSA >= -300e-6
   -CSA >= 0

Matrix notation

In the notation A.x >= b, where A is an matrix of coefficients, x is an array of parameter values, and b is a vector of scalars, these inequality constraints are:

   | 1  0  0  0  0  0  0  0  0 |                  |    0    |
   |                           |                  |         |
   |-1  0  0  0  0  0  0  0  0 |                  |   -1    |
   |                           |                  |         |
   | 0  1  0  0  0  0  0  0  0 |                  |    0    |
   |                           |                  |         |
   | 0 -1  0  0  0  0  0  0  0 |                  |   -1    |
   |                           |                  |         |
   | 0  0  1  0  0  0  0  0  0 |     | S2  |      |    0    |
   |                           |     |     |      |         |
   | 0  0 -1  0  0  0  0  0  0 |     | S2f |      |   -1    |
   |                           |     |     |      |         |
   |-1  1  0  0  0  0  0  0  0 |     | S2s |      |    0    |
   |                           |     |     |      |         |
   |-1  0  1  0  0  0  0  0  0 |     | te  |      |    0    |
   |                           |     |     |      |         |
   | 0  0  0  1  0  0  0  0  0 |  .  | tf  |  >=  |    0    |
   |                           |     |     |      |         |
   | 0  0  0  0  1  0  0  0  0 |     | ts  |      |    0    |
   |                           |     |     |      |         |
   | 0  0  0  0  0  1  0  0  0 |     | Rex |      |    0    |
   |                           |     |     |      |         |
   | 0  0  0  0 -1  1  0  0  0 |     |  r  |      |    0    |
   |                           |     |     |      |         |
   | 0  0  0  0  0  0  1  0  0 |     | CSA |      |    0    |
   |                           |                  |         |
   | 0  0  0  0  0  0  0  1  0 |                  | 0.9e-10 |
   |                           |                  |         |
   | 0  0  0  0  0  0  0 -1  0 |                  | -2e-10  |
   |                           |                  |         |
   | 0  0  0  0  0  0  0  0  1 |                  | -300e-6 |
   |                           |                  |         |
   | 0  0  0  0  0  0  0  0 -1 |                  |    0    |

Parameters:

• num_params (int) - The number of parameters in the model.
• model_type (str) - The model type, one of 'all', 'diff', 'mf', or 'local_tm'.
• spin (SpinContainer instance) - The spin data container. If this argument is supplied, then the spin_id argument will be ignored.
• spin_id (str) - The spin identification string.
• scaling_matrix (numpy diagonal matrix) - The diagonal, square scaling matrix.

_minimise_data_setup(self, data_store, min_algor, num_data_sets, min_options, spin=None, sim_index=None)

Set up all the data required for minimisation.

Parameters:

• data_store (class instance) - A data storage container.
• min_algor (str) - The minimisation algorithm to use.
• num_data_sets (int) - The number of data sets.
• min_options (list) - The minimisation options array.
• spin (SpinContainer instance) - The spin data container.
• sim_index (int) - The optional MC simulation index.

Returns: tuple

An insane tuple. The full tuple is (ri_data, ri_data_err, equations, param_types, param_values, r, csa, num_frq, frq, num_ri, remap_table, noe_r1_table, ri_types, num_params, xh_unit_vectors, diff_type, diff_params)

_relax_data_opt_structs(self, spin, sim_index=None)

Package the relaxation data into the data structures used for optimisation.

Parameters:

• spin (SpinContainer instance) - The spin container to extract the data from.
• sim_index (int) - The optional MC simulation index.

Returns: tuple

The structures ri_data, ri_data_err, num_frq, num_ri, ri_ids, frq, remap_table, noe_r1_table.

_reset_min_stats(self)

Reset all the minimisation statistics.

All global and spin specific values will be set to None.

calculate(self, spin_id=None, verbosity=1, sim_index=None)

Calculation of the model-free chi-squared value.

Parameters:

• spin_id (str) - The spin identification string.
• verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.
• sim_index (int) - The optional MC simulation index.

grid_search(self, lower=None, upper=None, inc=None, constraints=True, verbosity=1, sim_index=None)

The model-free grid search function.

Parameters:

• lower (array of numbers) - The lower bounds of the grid search which must be equal to the number of parameters in the model.
• upper (array of numbers) - The upper bounds of the grid search which must be equal to the number of parameters in the model.
• inc (array of int) - The increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model.
• constraints (bool) - If True, constraints are applied during the grid search (eliminating parts of the grid). If False, no constraints are used.
• verbosity (int) - A flag specifying the amount of information to print. The higher the value, the greater the verbosity.
• sim_index (int) - The index of the simulation to apply the grid search to. If None, the normal model is optimised.

minimise(self, min_algor=None, min_options=None, func_tol=None, grad_tol=None, max_iterations=None, constraints=False, scaling=True, verbosity=0, sim_index=None, lower=None, upper=None, inc=None)

Model-free minimisation function.

Three categories of models exist for which the approach to minimisation is different. These are:

Single spin optimisations: The 'mf' and 'local_tm' model types which are the model-free parameters for single spins, optionally with a local tm parameter. These models have no global parameters.

Diffusion tensor optimisations: The 'diff' diffusion tensor model type. No spin specific parameters exist.

Optimisation of everything: The 'all' model type consisting of all model-free and all diffusion tensor parameters.

Parameters:

• min_algor (str) - The minimisation algorithm to use.
• min_options (array of str) - An array of options to be used by the minimisation algorithm.
• func_tol (None or float) - The function tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
• grad_tol (None or float) - The gradient tolerance which, when reached, terminates optimisation. Setting this to None turns of the check.
• max_iterations (int) - The maximum number of iterations for the algorithm.
• constraints (bool) - If True, constraints are used during optimisation.
• scaling (bool) - If True, diagonal scaling is enabled during optimisation to allow the problem to be better conditioned.
• verbosity (int) - The amount of information to print. The higher the value, the greater the verbosity.
• sim_index (None or int) - The index of the simulation to optimise. This should be None if normal optimisation is desired.
• lower (array of numbers) - The lower bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
• upper (array of numbers) - The upper bounds of the grid search which must be equal to the number of parameters in the model. This optional argument is only used when doing a grid search.
• inc (array of int) - The increments for each dimension of the space for the grid search. The number of elements in the array must equal to the number of parameters in the model. This argument is only used when doing a grid search.