MDMC.control package

Submodules

MDMC.control.control module

A module for performing the refinement

class MDMC.control.control.Control(simulation: Simulation, exp_datasets: List[dict], fit_parameters: Parameters, minimizer_type: str = 'MMC', FoM_options: dict = None, reset_config: bool = True, MD_steps: int = None, equilibration_steps: int = 0, previous_history: str | Path = None, verbose: int = 0, print_all_settings: bool = False, **settings: dict)[source]

Bases: object

Controls the MDMC refinement

Parameters:

simulation (Simulation) – Performs a simulation for a given set of potential Parameter objects.
exp_datasets (list of dicts) –
Each dict represents an experimental dataset, containing the following keys:
- file_name (str) the file name
- type (str) the type of observable
- reader (str) the reader required for the file
- weighting (float) the weighting of the dataset to be used in the Figure of Merit calculation
- resolution : (dict, but can be str, float, or None) Should be a one-line dict of format {‘file’ : str} or {key : float} if {‘file’ : str}, the str should be a file in the same format as file_name containing results of a vanadium sample which is used to determine instrument energy resolution for this dataset. If {key : float}, the key should be the type of resolution function. allowed types are ‘gaussian’ and ‘lorentzian’ Can also be ‘lazily’ given as just a str or float. If just a string is given, it is assumed to be a filename. If just a float is given, it is assumed to be Gaussian. The float should be the instrument energy resolution as the FWHM in ueV (micro eV). If you have already accounted for instrument resolution in your dataset, this field can be set to None, and resolution application will be skipped. This must be done explicitly.
- rescale_factor (float, optional, defaults to 1.) applied to the experimental data when calculating the FoM to ensure it is on the same scale as the calculated observable
- auto_scale (bool, optional, defaults to False) set the rescale_factor automatically to minimise the FoM, if both rescale_factor and auto_scale are provided then a warning is printed and auto_scale takes precedence
- use_FFT (bool, optional, defaults to True) whether to use Fast Fourier Transforms in the calculation of dependent variables. FFT speeds up calculation but places restrictions on spacing in the independent variable domain(s). This option may not be supported for all ``Observable``s
Note that the default (and preferred) behaviour of the scaling settings requires that the dataset provided has been properly scaled and normalised for the refinement process. Arbitrary or automatic rescaling should be undertaken with care, as it does not take into account any physical aspects of scaling the data, such as the presence or absence of background events from peaks outside its range.
fit_parameters (Parameters, list of Parameter) – All parameters which will be refined. Note that any Parameter that is fixed, tied or equal to 0 will not be passed to the minimizer as these cannot be refined. Those with constraints set are still passed.
minimizer_type (str, optional) – The Minimizer type. Default is ‘MMC’.
FoM_options (dict of {str : str}, optional) –
Defines the details of the FigureOfMeritCalculator to use. Default is None, in which case the first option for each of the following keys is used:
- errors {‘exp’, ‘none’} Whether to weight the differences between MD and experimental data with the experimental error or not (errors from MD are not currently supported).
- norm {‘data_points’, ‘dof’, ‘none’} How to normalise the FoM, either by the total number of data_points (n), the degrees of freedom (n - m, where m is the number of parameters being varied), or not at all.
reset_config (bool, optional) – Determines if the configuration is reset to the end of the last accepted state. Default is True.
MD_steps (int, optional) – Number of molecular dynamics steps for each step of the refinement. When not provided, the minimum number of steps needed for successful calculation of the observables is used. If provided, the actual number of steps may be reduced to prevent running MD that won’t be used when calculating dependent variables. Default is None.
equilibration_steps (int, optional) – Number of molecular dynamics steps used to equilibrate the Universe in between each refinement step. When changes to the Parameters are small, this equilibration can be much shorter than the equilibration needed before starting the refinement process, but in general will vary depending on the details of the Universe and Parameters. Default is 0.
verbose (int, optional) – The level of verbosity: Verbose level -1 hides all outputs for tests. Verbose level 0 gives no information. Verbose level 1 gives final time for the whole method. Verbose level 2 gives final time and also a progress bar. Verbose level 3 gives final time, a progress bar, and time per step.
print_full_settings (bool, optional) – Whether to print all settings/attributes/parameters passed to this object, defaults to False.
**settings (dict, optional) –

n_steps: int
The maximum number of refinement steps to be. An optional parameter that, if specified, will be used in the refine method unless a different value of n_steps is explicitly passed when running refine.

cont_slicingbool, optional
Flag to decide between two possible behaviours when the number of MD_steps is larger than the minimum required to calculate the observables. If False (default) then the CompactTrajectory is sliced into non-overlapping sub-CompactTrajectory blocks for each of which the observable is calculated. If True, then the CompactTrajectory is sliced into as many non-identical sub-CompactTrajectory blocks as possible (with overlap allowed).

results_filename: str
The name of the file in which the results of the MDMC run will be stored

MC_norm: int
1 if the MMC minimiser is to be used for parameter optimisation.

use_averagebool, optional
Optional parameter relevant in case MD_steps is larger than the minimum required and the MD CompactTrajectory is sliced into sub-CompactTrajectory blocks. If True (default) the observables are averaged over the sub-CompactTrajectory blocks. If False they are not averaged.

data_printer: str, default ‘plaintext’
How to display the data during minimisation. Current options are ‘plaintext’ (default, plaintext printing) or ‘ipython’ (prettier HTML printing via iPython)

time_step_reductionsint, optional
The number of attempts to reduce the time_step of the simulation in order to fix an equilibration that keeps failing. Defaults to a value of 2.

Example

An example of an exp_dataset list is:

[{'file_name':data.LAMP_SQW_FILE,
  'type':'SQw',
  'reader':'LAMPSQw',
  'weight':1.,
  'resolution':{'file':data.LAMP_SQW_VAN_FILE}
  'rescale_factor':0.5},
 {'file_name:data.ANOTHER_FILE',
  'type':'FQt',
  'reader':'GENERIC_READER',
  'weight':0.5,
  'resolution':{'gaussian':2.35}
  'auto_scale':True}]

simulation

The Simulation on which is used to perform the refinement

Type:: Simulation

exp_datasets

One dict per experimental dataset used for the refinement

Type:: list of dicts

fit_parameters

All Parameter objects which will be refined

Type:: Parameters

minimizer

Refines the potential parameters.

Type:: Minimizer

observable_pairs

Experimental observable/MD observable pairs which are used to calculate the Figure of Merit

Type:: list of ObservablePairs

FoM_calculator

Calculates the FoM float from the observable_pairs.

Type:: FigureOfMeritCalculator

MD_steps

Number of molecular dynamics steps for each step of the refinement

Type:: int

calculate_max_FoM()[source]

Calculates a maximum Figure of Merit value by comparing a set of experimental observable data, to arrays consisting of numbers close to zero. For use when the MD Engine fails with a set of parameter values.

Returns:: max_FoM – value of maximum FoM
Return type:: int

engine_recovery_from_equil(n_steps: int, verbose: bool, output_log: str, work_dir: str, **settings: dict) → None[source]

Handles an MDEngineError thrown by the MD engine. Currently this error is only raised by LAMMPS.

The time_step is reduced, and the engine cleared, and then an equilibration is performed. If the equilibration is unsuccessful when the attempt limit is reached, an MDEngineError is raised.

Parameters:

n_steps (int) – Number of simulation steps to run.
verbose (bool, optional) – Whether to print statements upon starting and completing the run.
output_log (str, optional) – Log file for the MD engine to write to.
work_dir (str, optional) – Working directory for the MD engine to write to.

Return type:

None

equilibrate(n_steps: int = None, verbose: bool = False, output_log: str = None, work_dir: str = None, **settings: dict) → None[source]

Run molecular dynamics to equilibrate the Universe.

If the equilibration fails, a method to reduce the time_step and re-try, is called. If this re-try also fails, then an MDEngineError is raised.

Parameters:

n_steps (int) – Number of simulation steps to run.
verbose (bool, optional) – Whether to print statements upon starting and completing the run. Default is False.
output_log (str, optional) – Log file for the MD engine to write to. Default is None.
work_dir (str, optional) – Working directory for the MD engine to write to. Default is None.

minimize(n_steps: int, minimize_every: int = 10, verbose: bool = False, output_log: str = None, work_dir: str = None, **settings: dict) → None[source]

Performs an MD run intertwined with periodic structure relaxation. This way after a local minimum is found, the system is taken out of the minimum to explore a larger volume of the parameter space.

Parameters:

n_steps (int) – Total number of the MD run steps
minimize_every (int, optional) – Number of MD steps between two consecutive minimizations
verbose (bool, optional) – Whether to print statements when the minimization has been started and completed (including the number of minimization steps and time taken). Default is False.
output_log (str, optional) – Log file for the MD engine to write to. Default is None.
work_dir (str, optional) – Working directory for the MD engine to write to. Default is None.
**settings –

etol (float)
If the energy change between iterations is less than etol, minimization is stopped. Default depends on engine used.

ftol (float)
If the magnitude of the global force is less than ftol, minimization is stopped. Default depends on engine used.

maxiter (int)
Maximum number of iterations of a single structure relaxation procedure. Default depends on engine used.

maxeval (int)
Maximum number of force evaluations to perform. Default depends on engine used.

plot_results(filename: str = None, points: int = 100000, MH_norm: float = 20.0) → None[source]

Instantiates an insstance of the PlotResults class and generates a cornerplot from the data in self.results_filename

Parameters:

filename (str, optional) – The filename and path to the history file. Defaults to None which then uses self.results_filename
points (int, optional) – The number of samples to initially generate, defaults to 100,000
MH_norm (float, optional) – The denominator of the exponent, controlling how likley points are to be kept, defaults to 20.0

Returns:

corner plot – A plot displaying every parameter combination with their variances and covariances

Return type:

Matplotlib.figure.Figure

refine(n_steps: int = None) → None[source]

Refines the specified potential parameters

Parameters:: n_steps (int) – Maximum number of steps for the refinement. Must be specified either when creating the Control object or when calling this method. The value specified to this method supersedes the value passed (if any) when the Control object was created. If nothing is passed, the method will check if a number was specified when the Control object was created and use that value.

Examples

Perform a refinement with a maximum of 100 steps:

control.refine(100)

reset_engine() → None[source]: Clears and resets the MD engine when there is an error thrown by the equilibration or production methods. Currently this is only applicable to LAMMPS.

step(bad_param_location: bool = False) → None[source]

Do a full step: generate and run MD to calculate FoM for existing parameters, iterate parameters a step forward and reset MD (phasespace) if previous step was rejected and reset_config = true

Parameters:: bad_param_location (bool) – Represents whether the equilibration at these parameter value failed or not. If equilibration failed, value is True.

trial_reduce_time_step(reduction_factor) → None[source]

Reduces the time_step by the reduction factor specified.

Parameters:: reduction_factor (float) – represents the value which will be multiplied with the time_step in order to reduce it
Return type:: None

MDMC.control.plot_results module

A module for plotting data and results of a minimization.

class MDMC.control.plot_results.DataPrinter[source]

Bases: ABC

A class for printing data during a minimisation.

abstract print_data(history)[source]

Update table at the end of a refinement step.

Parameters: history

The history of the minimizer data is printed from.

abstract print_header(history)[source]

Create table headers at the start of refinement.

Parameters: history

The history of the minimizer data is printed from.

class MDMC.control.plot_results.IPythonDataPrinter[source]

Bases: DataPrinter

Prettier IPython data printer, for Jupyter Notebooks, etc.

print_data(history) → None[source]

Update table at the end of a refinement step.

Parameters: history

The history of the minimizer data is printed from.

print_header(history) → None[source]

Create table headers at the start of refinement.

Parameters: history

The history of the minimizer data is printed from.

class MDMC.control.plot_results.PlaintextDataPrinter[source]

Bases: DataPrinter

Plaintext data printer.

print_data(history) → None[source]

Update table at the end of a refinement step.

Parameters: history

The history of the minimizer data is printed from.

print_header(history) → None[source]

Create table headers at the start of refinement.

Parameters: history

The history of the minimizer data is printed from.

class MDMC.control.plot_results.PlotResults(filename: str, quantiles: list[float] = None, MH_norm: float = 20, points: int = 100000)[source]

Bases: object

A class to read in any completed refinement history file, create a Gaussain Process Optimizer and then do sampling on the result to create a corner plot.

Parameters:

filenamestr: path to the file to load in the refinement history
quantileslist, optional: optional, list of the quantiles to be plotted on the corner plot, defaults to [0.34, 0.5, 0.68], e.g. 1-sigma
MH_normfloat, optional: The Metropolis-Hastings normalising factor to determine if points should be kept or not, defaults to 20
pointsint, optional: Number of points to plot on the corner plot, defaults to 100,000

create_cornerplot() → None[source]

Performs a random sample across the coordinate space giving a predicted figure of merit at every point. Then removes points with poor figures of merit, according to a Metropolis-Hastings type rule, where the likelihood of keeping a point is dependant on the exponent of the difference between its figure of merit, and that of the best one found, divided by MC_norm. A corner plot is then returned (a matplotlib figure object), which can be displayed or exported.

Returns:: corner plot – A plot displaying every parameter combination with their variances and covariances
Return type:: Matplotlib.figure.Figure

get_measured_points() → tuple[source]: Opens the dataframe in filename and extracts the measured parameters names, values and associated figures of merit. Returns: ——– tuple of (parameter names, parameter coordinates, min and max parameters, FoM’s)

Module contents

Modules related to running a full MDMC refinement i.e. combining the MD and refinement subpackages

Contents

Control