Control

A module for performing the refinement

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

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.

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

equilibrate() → None[source]: Run molecular dynamics to equilibrate the Universe.

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)

step() → 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