MDMC.refinement.FoM package

Submodules

MDMC.refinement.FoM.ChiSquared_experror module

The class for Chi Squared figure of merit calculation with errors

class MDMC.refinement.FoM.ChiSquared_experror.ChiSquaredExpError(obs_pairs: list[ObservablePair], norm: str = 'data_points', n_parameters: int = None)

Bases: FigureOfMerit

Calculates the figure of merit as a sum of the square difference between data points for a single pair of observables, normalised by the errors and the number of data points, i.e. the reduced chi-squared.

Please see the documentation page explanation/figure-of-merit for mathematical details.

calculate_single_FoM(obs_pair: ObservablePair)

Calculates the chi-squared figure of merit for a single pair of observables, potentially rescaled if the experimental observable is not on an absolute scale.

Parameters:

obs_pair (ObservablePair) – An ObservablePair for which the FoM is calculated

Returns:

The FoM for the obs_pair

Return type:

float

MDMC.refinement.FoM.FoM_abs module

A module for Figure of Merits

class MDMC.refinement.FoM.FoM_abs.FigureOfMerit(obs_pairs: list[ObservablePair], norm: str = 'data_points', n_parameters: int = None)

Bases: ABC

Abstract class that defines methods common to all figure of merit calculators

Parameters:

• obs_pairs (list) – A list of ObservablePairs

• norm ({'data_points', 'dof', 'none'}, optional) – What method of normalisation to use when calculating the FoM for a single dataset. Default is ‘data_points’.

• n_parameters (int, optional) – The number of parameters being refined. Optional if norm is either ‘data_points’ or ‘none’, but required when ‘dof’. Default is None.

obs_pairs

A list of ObservablePairs

Type:

list

value

The Figure of Merit for all obs_pairs

Type:

float

calculate() → float

Calculates the FoM value by calculating the FoM for every ObservablePair

Returns:

A non-negative float Figure of Merit

Return type:

float

Raises:

ValueError – If calculated value of Figure of Merit is negative

abstract calculate_single_FoM(obs_pair: ObservablePair) → float

Performs the FoM calculation specific to each FoM

Parameters:

obs_pair (ObservablePair) – An ObservablePair for which the FoM is calculated

Returns:

The FoM for the obs_pair

Return type:

float

data_norm_factor(obs_pair: ObservablePair) → int

Calculates the normalisation factor for obs_pair. If self.norm is True, then returns the number of data points less the number of refinement parameters if ‘dof’ normalisation was chosen, or just the number of data points for the default ‘data_points’ normalisation. If self.norm is False, then returns 1.

Parameters:

obs_pair (ObservablePair) – An ObservablePair for which the normalisation factor is calculated

Returns:

The normalisation factor

Return type:

int

class MDMC.refinement.FoM.FoM_abs.ObservablePair(exp_obs: Observable, MD_obs: Observable, weight: float, rescale_factor: float = 1.0, auto_scale: bool = False)

Bases: object

Contains a pair of observables for calculating the FoM

Checks the validity of observables

Parameters:

• exp_obs (Observable) – An Observable with Observable.origin == 'experiment'

• MD_obs (Observable) – An Observable with Observable.origin == 'MD'

• weight (float) – The relative weight of this pair on a total FoM

• rescale_factor (float, optional) – Factor applied to exp_obs when calculating the FoM to ensure it is on the same scale as MD_obs. Default is 1..

• auto_scale (bool, optional) – If True, rescale_factor is set automatically to minimise the FoM for each step of the refinement, overriding a user specified value if set. Note that this process is purely statistical and does not account for physical effects that might impact the scaling. Default is False.

property MD_obs: Observable

Get or set the MD Observable

Setting the Observable checks its validity

Returns:

The MD Observable

Return type:

Observable

calculate_difference() → ndarray

Assumes a single dependent variable for each Observable

Returns:

An array with the same dimensions as the dependent_variables of the exp_obs and MD_obs. The array contains the difference between the dependent_variables taking the rescale_factor into account.

Return type:

numpy.ndarray

calculate_errors() → ndarray

Assumes a single dependent variable error for each Observable

Returns:

An array with the same dimensions as the errors of the exp_obs and MD_obs. The array contains the combination of the errors in quadrature, taking the rescale_factor into account.

Return type:

numpy.ndarray

calculate_exp_errors() → ndarray

Assumes a single dependent variable error for each Observable. Calculates only the experimental errors.

Returns:

An array with the same dimensions as the errors of the exp_obs, taking the rescale_factor into account.

Return type:

numpy.ndarray

check_dep_var() → None

Checks that Observable objects have the same dependent_variables and that are finite

check_errors() → None

Checks that an Observable has errors on the dependent_variable and that these are float and not NaN

check_indep_var() → None

Checks that Observable objects have the same independent_variables and that are finite

check_origin(origin: str) → None

Checks that the Observable.origin is correct

Parameters:

origin (str) – A string consisting of either 'experiment' or 'MD'

check_types() → None

Checks that Observable objects are of the same type

property exp_obs: Observable

Get or set the experimental Observable

Setting the Observable checks its validity

Returns:

The experimental Observable

Return type:

Observable

property n_averages: dict[str, int]

The number of separate, complete dependent variable calculations we have been able to perform for the Observable

Returns:

Each key represents a dependent variable, and the value is the number of times we have calculated it

Return type:

dict

validate_obs(obs: Observable, origin: str) → None

Performs checks to test the validity of an Observable

Tests that the Observable.origin is as expected. If the ObservablePair has another Observable (i.e. the other origin), then this tests that the independent_variables are identical, the dependent_variables have the same shape, the errors have the same shape, and that the Observable objects are of the same type.

Parameters:

• obs (Observable) – The Observable to validate

• origin (str) – The Observable.origin ('experiment' or 'MD')

Raises:

• AssertionError – If the Observable.origin is not the same as the origin Parameter

• AssertionError – If Observable does not have identical independent_variables to any Observable of the other Observable.origin that already exists in the ObservablePair

• AssertionError – If Observable does not have identical dependent_variables to any Observable of the other Observable.origin that already exists in the ObservablePair

• AssertionError – If Observable does not have identical errors to any Observable of the other Observable.origin that already exists in the ObservablePair

• AssertionError – If Observable does not have identical type to any Observable of the other Observable.origin that already exists in the ObservablePair

static validate_weight(weight: float) → None

Performs checks to test the validity of the weight

Parameters:

weight (float) – The weight to be validated

Raises:

AssertionError – If the weight is not positive or is infinite

property weight: float

Get or set the relative weight of this pair on a total FoM

Returns:

The relative weight

Return type:

float

Raises:

TypeError – If weight is set with a non-numeric

MDMC.refinement.FoM.FoM_factory module

Factory class for generating Figure of Merits And ObservablePair class fro defining the obseravble pairs used to calculate the Figure of Merit

class MDMC.refinement.FoM.FoM_factory.FoMFactory

Bases: object

Provides a factory for creating a Figure of Merit also called FoM. Any FoM within the FoM folder can be created with a string of the class name, as long as it is a subclass of FigureOfMerit.

static create_FoM(module_name, obs_pairs, norm: str = 'data_points', n_parameters: int = None)

Returns:

A Figure of Merit specified by module_name

Return type:

FigureOfMerit

static get_FoM_names()

Get the names of available Figure of Merits(FoM)

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

Returns:

A list of str with the names of the available Figure of Merits objects

Return type:

list

MDMC.refinement.FoM.RSquared_noneerror module

The class for R Squared figure of merit calculation with no errors

class MDMC.refinement.FoM.RSquared_noneerror.RSquared_noneerror(obs_pairs: list[ObservablePair], norm: str = 'data_points', n_parameters: int = None)

Bases: FigureOfMerit

Calculates the weighted sum of the Figure of Merits for a number of datasets:

\[FoM_{total} = \frac{\sum_{i} FoM_{i}}{\sum_{i} w_{i}}\]

Here the weighted Figure of Merit for the \(i\)-th dataset, \(FoM_{i}\), is given by the sum of the square difference between data points for a single ObservablePair, i.e. the reduced chi-squared:

\[FoM_{i} = \frac{w_{i}}{\nu_{i}} \sum_{j} (D_{j}^{exp} - D_{j}^{sim})^2\]

where the sum is over the \(N_{i}\) data points in the ObservablePair corresponding to the \(i\)-th dataset, and the normalisation factor \(\nu_{i}\) is either \(N_{i}\), \(N_{i} - M\) where \(M\) is the number of fitting parameters, or \(1\). \(w_{i}\) is an importance weighting assigned to the \(i\)-th dataset. \(D_{j}\) are the individual data points in the 1-D or 2-D array of the experimental Observable (\(exp\)) or simulated Observable (\(sim\)). Note that the subtraction and division over the arrays are element-wise. Note also that if the experimental Observable is not on an absolute scale, an additional rescale_factor can be specified (or automatically determined) by the ObservablePair to scale the experimental data points and errors by a simple linear scaling.

calculate_single_FoM(obs_pair: ObservablePair)

Performs the square difference for an ObservablePair If obs_pair.auto_scale is True, then this will also set obs_pair.rescale to the value which minimizes the FoM. If we label rescale_factor\(=\lambda\) then the minimum of the FoM is obtained as:

\[\begin{split}FoM_{i}(\lambda) &=& w_{i} \sum_{j} \left(\lambda*D_{j}^{exp} - D_{j}^{sim}\right)^2 \\\\ \left. \frac{dFoM_{i}}{d\lambda}\right|_{\lambda=\lambda_{min}} &=& 0 \\\\ \lambda_{min} &=& \frac{A}{B} \\\\\end{split}\]

where we have:

\[\begin{split}A &=& \sum_{j} D_{j}^{exp}*D_{j}^{sim} \\\\ B &=& \sum_{j}\left(D_{j}^{exp}\right)^2\end{split}\]

Parameters:

obs_pair (ObservablePair) – An ObservablePair for which the FoM is calculated

Returns:

The FoM for the obs_pair

Return type:

float

Module contents

A module for Figure of Merit calculation