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: Optional[dict] = None, reset_config: bool = True, MD_steps: Optional[int] = None, equilibration_steps: int = 0, convergence_tol: float = 1e-05, min_refinement_steps: int = 2, max_parameter_change: float = 0.01, verbose: int = 0, **settings: dict)[source]

Controls the MDMC refinement

  • 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.

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

  • 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.

  • convergence_tol (float, optional) – The relative tolerance used to determine if a refinement has converged. If the Figure of Merit and all Parameters change less than this tolerance between two accepted refinement steps, the refinement stops. Default value is 1e-5.

  • min_refinement_steps (int, optional) –

    The minimum number of refinement steps before the refinement process can stop

    if all parameters and the Figure of Merit have converged. Default value is 2.

    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 Trajectory is sliced into non-overlapping sub-Trajectory blocks for each of which the observable is calculated. If True, then the Trajectory is sliced into as many non-identical sub-Trajectory blocks as possible (with overlap allowed).

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

  • verbose (int, optional) – The level of verbosity: 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.

  • **settings (dict, optional) – Settings to be passed into other functions, e.g. MC_norm=1 for MC optimiser if MMC minimiser is used.


An example of an exp_dataset list is:


The Simulation on which is used to perform the refinement




One dict per experimental dataset used for the refinement


list of dicts


All Parameter objects which will be refined




Refines the potential parameters.




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


list of ObservablePairs


Calculates the FoM float from the observable_pairs.




Number of molecular dynamics steps for each step of the refinement




Run molecular dynamics to equilibrate the Universe.

refine(n_steps: int)[source]

Refines the specified potential parameters


n_steps (int) – maximum number of steps for the refinement


Perform a refinement with a maximum of 100 steps:



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