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 nametype
(str) the type of observablereader
(str) the reader required for the fileweighting
(float) the weighting of the dataset to be used in the Figure of Merit calculationresolution
: (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 asfile_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 inueV
(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 observableauto_scale
(bool, optional, defaults to False) set therescale_factor
automatically to minimise the FoM, if bothrescale_factor
andauto_scale
are provided then a warning is printed andauto_scale
takes precedenceuse_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 isfixed
,tied
or equal to 0 will not be passed to the minimizer as these cannot be refined. Those withconstraints
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 theParameters
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 theUniverse
andParameters
. 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 ofn_steps
is explicitly passed when runningrefine
.- 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. IfFalse
(default) then theCompactTrajectory
is sliced into non-overlapping sub-CompactTrajectory
blocks for each of which the observable is calculated. IfTrue
, then theCompactTrajectory
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 MDCompactTrajectory
is sliced into sub-CompactTrajectory
blocks. IfTrue
(default) the observables are averaged over the sub-CompactTrajectory
blocks. IfFalse
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:
- 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:
- 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:
- 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:
- 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 theControl
object was created. If nothing is passed, the method will check if a number was specified when theControl
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.
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.
- class MDMC.control.plot_results.IPythonDataPrinter[source]
Bases:
DataPrinter
Prettier IPython data printer, for Jupyter Notebooks, etc.
- class MDMC.control.plot_results.PlaintextDataPrinter[source]
Bases:
DataPrinter
Plaintext data printer.
- 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
Module contents
Modules related to running a full MDMC refinement i.e. combining the MD and refinement subpackages
Contents
Control