MDMC.refinement.minimizers package

Submodules

MDMC.refinement.minimizers.GPO module

The Gaussian-Process-Optimizer minimizer class

class MDMC.refinement.minimizers.GPO.GPO(control: Control, parameters: Parameters, previous_history: Path | str | None = None, **settings: dict)

Bases: Minimizer

Minimizer which uses Gaussian process optimisation to find the global minimum figure of merit.

The optimizer comes from scikit-optimize https://scikit-optimize.github.io/stable/modules/generated/skopt.optimizer.Optimizer.html It acts in an ask/tell architecture, where the optimizer is “asked” for the best parameter values to measure at, then when the measurement is complete, we “tell” the optimizer what the result was and it updates its model. The optimizer is configured to cycle between prioritising exploration of the space and exploitation of the minima, in order to find the global minimum without becoming stuck in a local minimum.

The first n_initial points will be spaced according to a latin hypercube, to cover the available space, subsequent points will then be chosen according to the acquisition function and the measured values. Due to the potential large jumps between the points, a reasonable amount of equlibration of the MD simulation is likely required. This optimizer is likely to be the fastest converging (fewest MD steps) option for MDMC.

Please see the documentation page explanation/minimizers for more information.

Parameters:

• control (Control) – The Control object which uses this Minimizer.

• parameters (Parameters) – The parameters in the simulation Universe to be optimized.

• previous_history (Path) – The Path to a results file containing previous refinement data.

• Settings

• ----------

• n_initial (int, optional) – The number of points used for the initial latin hypercube coverage of the parameter space. Optional. If no value is given it defaults to 20. Note that if the associated Control objects has a maximum number of refinement steps (defined in Control.n_steps) which is smaller than n_initial then that value will be used instead.

history_columns

list of the column titles, and parameter names in the minimizer history

Type:

list[str]

change_parameters() → None

Selects a new value for each parameter from the array of parameter values to interrogate from the parameter_point_array.

extract_result() → list

Extracts the measured & predicted FoM and point(s)

Returns:

list_of_outputs – A list of: coordinates of lowest FoM, Minimum FoM, Coordinate of best predicted FoM, Minimum predicted FoM

Return type:

list

format_result_string(minimizer_output: list) → str

Parameters:

minimizer_output (list) – A list of: coordinates of lowest FoM, Minimum FoM, Coordinate of best predicted FoM, Minimum predicted FoM

Returns:

output_string – An output string, formatted with the appropriate information about measured and predicted points

Return type:

str

has_converged() → bool

Checks if the refinement process has finished, i.e. if the number of points is equal to or greater than the number of maximum refinement points of the associated Control object.

Returns:

Whether or not the minimizer has converged.

Return type:

bool

property history_columns: list[str]

Returns column labels of the history

Returns:

A list of str containing all the column labels in the history

Return type:

list[str]

reset_parameters() → None

Not necessary for this minimizer

set_parameter_values(parameter_names: list[str], values: list[float]) → None

Assigns a new value to each parameter (specified by the parameter.name)

Parameters:

• parameter_names (list[str]) – A list of the names of the parameters whose values are to be set

• values (list[float]) – A list of the values to be set for each parameter

step(FoM: float) → None

Increments the minimization by a step, tells the optimizer the most recent measured point asks for the coordinates of the next point, updates the history, checks for convergance and then changes parameters if an additional step is required.

Parameters:

FoM (float) – The current figure of merit value.

MDMC.refinement.minimizers.GPR module

The Gaussian-Process-Regression minimizer class

class MDMC.refinement.minimizers.GPR.GPR(control: Control, parameters: Parameters, previous_history: Path | str | None = None, **settings: dict)

Bases: Minimizer

Minimizer employing Gaussian Process Regression. Creates a predefined array of points across all parameters and performs a simulation at each point. Then performs a Gaussian process regression fit across all measured points and predicts across a finer grid, before returning the predicted minimum FoM and the associated parameter values. This minimizer works best when physically realistic constraints are applied, in the absence of being provided with them, the minimizer sets constraints equal to 20% of the current parameter values.

Parameters:

• control (Control) – The Control object which uses this Minimizer.

• parameters (Parameters) – The parameters in the simulation Universe to be optimized

history_columns

list of the column titles, and parameter names in the minimizer history

Type:

list[str]

GPR_fit(filename: str | None = None, alpha: float | None = 5, length_scale: float | None = 4)

Reads in the contents of the supplied filename, assumes it is the output of a refinement and can be read into a dataframe with the relevant parameters. Uses the recorded points file to perform a Gaussian process regression (https://scikit-learn.org/stable/modules/gaussian_process.html) and fit the points to some kernel, here using an RBF kernel.

Parameters:

• filename (str, optional) – The filename or full path to a comma separated value file containing the full output of the refinement. Defaults to None, but if results_filename is set by Control then this is passed into GPR as self.results_filename and used here.

• alpha (float, optional) – Hyperparameter for the fitting, which can represent Gaussian noise in measurement points, e.g. how much variation in the output you expect between MD runs. Defaults to 5.

• length_scale (float, optional) – Hyperparameter for the fitting, which can represent how quickly the kernel is able to change/oscillate. Defaults to 4.0.

Returns:

• GaussianProcessRegressor (GaussianProcessRegressor) – The fitted points using GPR

• Minimum figure of merit (float)

• Minimum parameter values (float)

static GPR_predict(input_regressor, points: float | None = 100) → tuple[list[tuple[float]], ndarray]

Takes a fitted Gaussian process regressor from GPR_fit, creates an fine array of points between the minimum and maximum measured parameter values and predicts the FoM at each one of these points.

Parameters:

• input_regressor (GaussianProcessRegressor) – A fitted Gaussian Process regressor object

• points (int, optional) – Number of points to predict the GPR over. Defaults to 100

Returns:

• point_array (list[tuple[float]]) – The list of coordinates at which the predictions are made

• prediction (numpy.ndarray) – A list of predicted figure of merit surface at each coordinate in the point_array

change_parameters() → None

Selects a new value for each parameter from the array of parameter values to interrogate from the parameter_point_array.

static create_bounds(parameter: Parameter, fraction: float = 0.3) → tuple[float, float]

Returns either the parameter constraints (bounds) or bounds for each parameter equal to the parameter value =/- fraction*parameter.value, defaulting to +-30%. Raises a ValueError if value is zero and has no constraints since it is not possible to make a guess.

Parameters:

• parameter (Parameter) – A MDMC Parameter

• fraction (optional, float) – The fractional size of the bound, defaults to 0.3 == +-30%

Returns:

• lower_bound (float) – The lower bound for the parameter

• upper_bound (float) – The upper bound for the parameter

Raises:

ValueError – If parameter.value is zero and no constraints have been set for it there is no sensible way to guess bounds.

create_parameter_point_array(parameters: Parameters) → tuple[list[str], list[tuple]]

Takes or creates the constraints of the parameters to be minimised and makes an array of points, placed on a Latin hypercube covering the space defined by the constraints. The resulting array of coordinates is self.control.n_steps long.

Parameters:

parameters (Parameters) – All Parameter objects that are being refined.

Returns:

• parameter_names (list) – Ordered list of names of parameters

• point_array (list) – list of parameter coordinates to be simulated

extract_result() → list

Extracts the measured & predicted FoM and point(s)

Returns:

A list of: coordinates of lowest FoM, Minimum FoM, Coordinate of best predicted FoM, Minimum predicted FoM

Return type:

list

format_result_string(minimizer_output: list) → str

Parameters:

minimizer_output (list) – A list of: coordinates of lowest FoM, Minimum FoM, Coordinate of best predicted FoM, Minimum predicted FoM

Returns:

An output string, formatted with the appropriate information about measured and predicted points

Return type:

str

static global_minimum_position(predicted_FOMs: ndarray, measured_parameter_coordinates: list[float]) → tuple[ndarray, float]

Gives the coordinates of the global minimum of the predicted figure of merit surface.

Parameters:

• predicted_FOMs (numpy.ndarray) – A numpy array of the predicted figures of merit

• measured_parameter_coordinates (list) – A list of the coordinates corresponding to the points at which the FoM was predicted

Returns:

• minimum_parameters (numpy.ndarray) – The parameter coordinates where the minimum figure of merit is predicted to be

• min_FoM (float) – The predicted minimum figure of merit value

has_converged() → bool

Checks if the refinement process has finished, i.e. if all points across the parameter_point_array have been measured.

Returns:

Whether or not the minimizer has converged.

Return type:

bool

property history_columns: list[str]

Returns column labels of the history

Returns:

A list of str containing all the column labels in the history

Return type:

list[str]

reset_parameters() → None

Resets the Parameter values to the last set of values in parameter_point_array

set_parameter_values(parameter_names: list[str], values: list[float]) → None

Assigns a new value to each parameter (specified by the parameter.name)

Parameters:

• parameter_names (list[str]) – A list of the names of the parameters whose values are to be set

• values (list[float]) – A list of the values to be set for each parameter

step(FoM: float) → None

Increments the minimization by a step

Parameters:

FoM (float) – The current figure of merit value.

MDMC.refinement.minimizers.MMC module

The Metropolis-Hastings minimizer class

class MDMC.refinement.minimizers.MMC.MMC(control: Control, parameters: Parameters, previous_history: Path | str | None = None, **settings: dict)

Bases: Minimizer

Minimizer employing the Metropolis-Hastings algorithm

Parameters:

• control (Control) – The Control object which uses this Minimizer.

• MC_norm (float) – Normalization parameter for MC which determines the accept/reject ratio, default is 1.0

• max_parameter_change (float, optional) – Maximum factor by which a Parameter can change each step of the refinement. Defaults to 0.01

• conv_tol (float, optional) – The relative tolerance of the convergence check. Defaults to 1e-5

• min_steps (int, optional) – The number of refinement steps with an accepted state change after which convergence is checked. If the number of accepted state changes is less than this, then the refinement is deemed as not converged. Defaults to 2

• distribution (str, optional) – The distribution from which Parameter changes are selected. Defaults to ‘uniform’

history_columns

list of the column titles for the minimizer history

Type:

list[str]

DISTRIBUTION = {'uniform': <bound method RandomState.uniform of RandomState(MT19937)>}

change_parameters() → None

Selects a new value for each parameter from a distribution centered around the current value.

Note that for Parameter``s with ``constraints set, any proposed new value that would lie outside the range of the constraint is clipped to the lower or upper limit as appropriate.

Parameters:

parameters (Parameters) – All Parameter objects that are being refined

change_state() → bool

Stochastic determination of whether the state should change based on the FoM

Returns:

True if the state should be change

Return type:

bool

extract_result() → list[str]

Extracts the result data from the history of the minimizer run

Returns:

output_data – A list of: last accepted point coordinates, last accepted point FoM value, best point coordinates, best point FoM

Return type:

list[str]

format_result_string(minimizer_output: list) → str

Formats a string output for the results of an MMC minimizer run

Parameters:

minimizer_output (list) – A list of: last accepted point coordinates, last accepted point FoM value, best point coordinates, best point FoM

Returns:

output_string – A string containing the following: whether the minimizer has converged, last parameters, last FoM value, optimal (lowest FoM) parameters, optimal (lowest) FoM value

Return type:

str

has_converged() → bool

Checks if the refinement process has converged on a stable solution. Specifically, it checks if the Figure of Merit and the parameters being refined have all changed less than the relative conversion tolerance (conv_tol) between the last two accepted refinement steps. It also allows specifying a minimum number of refinement steps (min_steps) that must have been accepted before checking for convergence.

Returns:

Whether or not the minimizer has converged.

Return type:

bool

property history_columns: list[str]

Returns column labels of the history

Returns:

A list of str containing all the column labels in the history

Return type:

list[str]

reset_parameters() → None

Resets the Parameter values to the values from the previous MMC step

step(FoM: float) → None

Increments the minimization by a step

Parameters:

FoM (float) – The current figure of merit value.

MDMC.refinement.minimizers.minimizer_abs module

A module for all minimizers which can be iterated to refine the potential parameters

class MDMC.refinement.minimizers.minimizer_abs.Minimizer(control: Control, parameters: Parameters, previous_history: str | Path = None)

Bases: ABC

An abstract class with methods common to all minimizers

Parameters:

• control (Control) – The Control object which uses this Minimizer.

• parameters (Parameters or list of Parameter) – A list of Parameter objects which will be fit

history

A list of minimization history, where each element contains the FoM, a list of the Parameters and a str with whether the step was Accepted or Rejected.

Type:

list

FoM

The FoM from the current Minimizer step

Type:

float

FoM_old

The FoM from the previous Minimizer step

Type:

float

parameters

A Parameters object containing the Parameter objects being fitted

Type:

Parameters

parameters_old_values

A Parameters object containing the values of the Parameter objects from the previous minimizer step

Type:

Parameters

abstract change_parameters() → None

Selects a new value for each Parameter.

enforcing_minimizer_compatibility(column_names, history) → None

Checks that the refinement file has the correct set up to be used with the current minimizer and makes the necessary changes for this compatibility.

Parameters:

• column_names (list) –

  A list of the columns names from a previous refinement file, excluding any step number

  column.

• history (list of lists) –

  A list, where each element is a subsequent list with parameter values and FoM value

  for each step in a previous refinement.

Raises:

Exception – If changing _history for minimizer compatibility fails.

abstract extract_result() → list[str]

Obtains the result of the minimizer to be presented/formatted

Returns:

A list of strings representing the data points output by the minimizer to be formatted into a string

Return type:

list[str]

abstract format_result_string(minimizer_output: list) → str

Formats a string output for the results of the minimiser class.

Parameters:

minimizer_output (list) – A list of printable values representing the data points output by the minimizer to be formatted into a string

Returns:

A string encompassing the output of the minimizer.

Return type:

str

get_parameters_old_values(parameters: Parameters, column_names: list, history: list)

Retrieves the last set of parameters from a file containing data of previous refinement steps.

Parameters:

• column_names (list) – A list of the columns names for the past refinement data.

• history (list of lists) –

  A list, where each element is a subsequent list with parameter values and FoM value

  for each step in a previous refinement.

Raises:

Exception – If the last parameter values can not be retrieved from history.

Returns:

• dict (if there is a history file loaded) – dictionary of parameter values from the last step.

• None (if there is no history file loaded) – None type.

abstract has_converged() → bool

Checks if the refinement process has converged/finished. The condition which needs to be met to make this True is optimizer dependent, but might be that the refinement has repeatedly returned a very similar FoM which meets some threshold, determining that it is close to the optimal, or it could be that the minimizer has measured at all the parameter points that were specified and it should now predict the best position.

Returns:

Whether or not the minimizer has converged/finished.

Return type:

bool

property history: DataFrame

Get the history of the minimizer, with a single entry for each step of the minimizer

Returns:

Contains the minimizer variables for each refinement step. The variables which are included is concrete implementation specific, and is specified by history_columns.

Return type:

pd.DataFrame

abstract property history_columns: list[str]

Get the column titles for the minimizer history

Returns:

A ‘list’ of ‘str’ specifying the column titles for the minimizer history

Return type:

list

load_history(history: Path) → tuple

Uses the previous_history variable to load a file of previous refinement steps. It then formats this into the column names and the actual parameter values. The loaded data is stored as numpy arrays.

Parameters:

history (Path) – A file path which contains previous refinement data.

Raises:

ValueError – If the file with the previous history data can not be found.

Returns:

list of columns names, and a list containing a list for each refinement step

from the loaded history file.

Return type:

tuple

present_result() → str

Extracts and returns the most appropriate output for the minimiser class, in an appropriate format e.g. minimum FOM and parameter values

Returns:

A formatted string representing the output of the minimizer

Return type:

str

abstract reset_parameters() → None

Resets the parameters to a previous state

abstract step(FoM: float) → None

Increments the minimization by a step

Parameters:

FoM (float) – The current figure of merit value.

write_history(filename) → None

Write the minimizer history to a csv file

Parameters:

filename (str) – The name of the output file

MDMC.refinement.minimizers.minimizer_factory module

Factory class for generating minimizers

class MDMC.refinement.minimizers.minimizer_factory.MinimizerFactory

Bases: object

Provides a factory for creating a Minimizer. Any minimizer within the minimizers folder can be created with a string of the class name, as long as it is a subclass of Minimizer.

static create_minimizer(module_name: str, control: Control, parameter: list[str], previous_history: Path = None, **settings: dict) → Minimizer

Checks that the module is a supported minimzer and instantiates it as a minimizer.

Parameters:

• module_name (str) – The name of the module to be used as the minimizer, e.g. ‘MMC’

• control (Control) – The Control object which uses this Minimizer.

• parameter (list[str]) – List of parameters to be refined

• **settings (dict, optional) – Settings to be passed to the created minimiser, e.g. MC_norm=1.0 if MMC minimiser is used or n_points=8 if GPR or GPO is used

Returns:

A Minimizer specified by module_name

Return type:

Minimizer

static get_minimizer_names() → list[str]

Get the names of available minimizer

Requires all Minimizer derived classes to be in modules of the same name

Returns:

A list of str with the names of the available Minimizer objects

Return type:

list[str]

Module contents

A module for refinement minimizers.