Constraint contains parent classes for all constraints. A Constraint is used to set certain rules for the stochastic engine to evolve the atomic system. Therefore it has become possible to fully customize and set any possibly imaginable rule.

class fullrmc.Core.Constraint.Constraint

A constraint is used to direct the evolution of the atomic configuration towards the desired and most meaningful one.

constraintId

Constraint unique ID create at instanciation time.

constraintName

Constraints unique name in engine given when added to engine.

engine

Stochastic fullrmc’s engine instance.

usedFrame

Get used frame in engine. If None then engine is not defined yet

computationCost

Computation cost number.

state

Constraint’s state.

tried

Constraint’s number of tried moves.

accepted

Constraint’s number of accepted moves.

used

Constraint’s used flag. Defines whether constraint is used in the stochastic engine at runtime or set inactive.

varianceSquared

Constraint’s varianceSquared used in the stochastic engine at runtime to calculate the total constraint’s standard error.

standardError

Constraint’s standard error value.

originalData

Constraint’s original data calculated upon initialization.

data

Constraint’s current calculated data.

activeAtomsDataBeforeMove

Constraint’s current calculated data before last move.

activeAtomsDataAfterMove

Constraint’s current calculated data after last move.

afterMoveStandardError

Constraint’s current calculated StandardError after last move.

amputationData

Constraint’s current calculated data after amputation.

amputationStandardError

Constraint’s current calculated StandardError after amputation.

multiframeWeight

Get constraint weight towards total in a multiframe system.

is_in_engine(engine)

Get whether constraint is already in defined and added to engine. It can be the same exact instance or a repository pulled instance of the same constraintId

Parameters: engine (stochastic fullrmc engine): Engine instance. result (boolean): Whether constraint exists in engine.
set_variance_squared(value, frame=None)

Set constraint’s variance squared that is used in the computation of the total stochastic engine standard error.

Parameters: value (number): Any positive non zero number. frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes will be targeted. If subframe is given, all other multiframe subframes will be targeted.
set_computation_cost(value, frame=None)

Set constraint’s computation cost value. This is used at stochastic engine runtime to minimize computations and enhance performance by computing less costly constraints first. At every step, constraints will be computed in order starting from the less to the most computationally costly. Therefore upon rejection of a step because of an unsatisfactory rigid constraint, the left un-computed constraints at this step are guaranteed to be the most time coslty ones.

Parameters: value (number): computation cost. frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes will be targeted. If subframe is given, all other multiframe subframes will be targeted.
set_used(*args, **kwargs)

Set used flag.

Parameters: value (boolean): True to use this constraint in stochastic engine runtime. frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes will be targeted. If subframe is given, all other multiframe subframes will be targeted.
set_state(value)

Set constraint’s state. When constraint’s state and stochastic engine’s state don’t match, constraint’s data must be re-calculated.

Parameters: value (object): Constraint state value.
set_tried(value)

Set constraint’s number of tried moves.

Parameters: value (integer): Constraint tried moves value.
increment_tried()

Increment number of tried moves.

set_accepted(value)

Set constraint’s number of accepted moves.

Parameters: value (integer): Constraint’s number of accepted moves.
increment_accepted()

Increment constraint’s number of accepted moves.

set_standard_error(value)

Set constraint’s standardError value.

Parameters: value (number): standard error value.
set_data(value)

Set constraint’s data value.

Parameters: value (number): constraint’s data.
set_active_atoms_data_before_move(value)

Set constraint’s before move happens active atoms data value.

Parameters: value (number): Data value.
set_active_atoms_data_after_move(value)

Set constraint’s after move happens active atoms data value.

Parameters: value (number): data value.
set_after_move_standard_error(value)

Set constraint’s standard error value after move happens.

Parameters: value (number): standard error value.
set_amputation_data(value)

Set constraint’s after amputation data.

Parameters: value (number): data value.
set_amputation_standard_error(value)

Set constraint’s standardError after amputation.

Parameters: value (number): standard error value.
reset_constraint(reinitialize=True, flags=False, data=False, frame=None)

Reset constraint.

Parameters: reinitialize (boolean): If set to True, it will override the rest of the flags and will completely reinitialize the constraint. flags (boolean): Reset the state, tried and accepted flags of the constraint. data (boolean): Reset the constraints computed data. frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes will be targeted. If subframe is given, rest of multiframe subframes will not be targeted.
update_standard_error()

Compute and set constraint’s standard error by calling compute_standard_error method and passing constraint’s data.

get_constraints_properties(frame)

Get a dictionary look up table of constraint’s properties

Parameters: frame (string): frame to pull and build contraint data. It can be a traditional frame, a multiframe or a subframe propertiesLUT (dictionary): properties value look up table. Keys are described herein. All keys start with ‘frames-‘ and values are list of properties for every and each frame. frames-name: list of all frames name frames-weight: list of all frames weight frames-number_of_removed_atoms: list of number of removed atoms from each frame frames-constraint: list of constraint copy frames-data: list of constraint data frames-standard_error: list of all frames standard error
get_constraint_value()

Method must be overloaded in children classes.

get_constraint_original_value()

Method must be overloaded in children classes.

compute_standard_error()

Method must be overloaded in children classes.

compute_data(update=True)

Method must be overloaded in children classes.

compute_before_move(realIndexes, relativeIndexes)

Method must be overloaded in children classes.

compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Method must be overloaded in children classes.

accept_move(realIndexes, relativeIndexes)

Method must be overloaded in children classes.

reject_move(realIndexes, relativeIndexes)

Method must be overloaded in children classes.

compute_as_if_amputated(realIndex, relativeIndex)

Method must be overloaded in children classes.

compute_as_if_inserted(realIndex, relativeIndex)

Method must be overloaded in children classes.

accept_amputation(realIndex, relativeIndex)

Method must be overloaded in children classes.

reject_amputation(realIndex, relativeIndex)

Method must be overloaded in children classes.

accept_insertion(realIndex, relativeIndex)

Method must be overloaded in children classes.

reject_insertion(realIndex, relativeIndex)

Method must be overloaded in children classes.

export(fileName, frame=None, format='%s', delimiter='\t', comments='#')

Export constraint data to text file or to an archive of files.

Parameters: fileName (path): full file name and path. frame (None, string): frame name to export data from. If multiframe is given, multiple files will be created with subframe name appended to the end. format (string): string format to export the data. format is as follows (%[flag]width[.precision]specifier) delimiter (string): String or character separating columns. comments (string): String that will be prepended to the header.
plot(frame=None, axes=None, subAdParams={'bottom': None, 'hspace': 0.4, 'left': None, 'right': None, 'top': None, 'wspace': None}, dataParams={'label': 'Y', 'linewidth': 2}, xlabelParams={'size': 10, 'xlabel': 'Core-Shell atoms'}, ylabelParams={'size': 10, 'ylabel': 'Coordination number'}, xticksParams={'fontsize': 8, 'rotation': 90}, yticksParams={'fontsize': 8, 'rotation': 0}, legendParams={'fontsize': 8, 'frameon': False, 'loc': 'upper right', 'ncol': 1}, titleParams={'fontsize': 10, 'label': '@{frame} (${numberOfRemovedAtoms:.1f}$ $rem.$ $at.$) $Std.Err.={standardError:.3f}$ - $used$ $({used})$'}, gridParams=None, show=True, **paramsKwargs)

Plot constraint data. This can be overloaded in children classes.

Parameters: frame (None, string): The frame name to plot. If None, used frame will be plotted. ax (None, matplotlib Axes): matplotlib Axes instance to plot in. If None is given a new plot figure will be created. subAdParams (None, dict): matplotlib.artist.Artist.subplots_adjust parameters subplots adjust parameters. dataParams (None, dict): constraint data plotting parameters xlabelParams (None, dict): matplotlib.axes.Axes.set_xlabel parameters. ylabelParams (None, dict): matplotlib.axes.Axes.set_ylabel parameters. legendParams (None, dict):matplotlib.axes.Axes.legend parameters. xticksParams (None, dict):matplotlib.axes.Axes.set_xticklabels parameters. yticksParams (None, dict):matplotlib.axes.Axes.set_yticklabels parameters. titleParams (None, dict): matplotlib.axes.Axes.set_title parameters gridParams (None, dict): matplotlib.axes.Axes.grid parameters show (boolean): Whether to render and show figure before returning. figure (matplotlib Figure): matplotlib used figure. axes (matplotlib Axes): matplotlib used axes.
class fullrmc.Core.Constraint.ExperimentalConstraint(experimentalData, dataWeights=None, scaleFactor=1.0, adjustScaleFactor=(0, 0.8, 1.2))

Experimental constraint is any constraint related to experimental data.

Parameters: engine (None, fullrmc.Engine): Constraint’s stochastic engine. experimentalData (numpy.ndarray, string): Experimental data goiven as numpy.ndarray or string path to load data using numpy.loadtxt method. dataWeights (None, numpy.ndarray): Weights array of the same number of points of experimentalData used in the constraint’s standard error computation. Therefore particular fitting emphasis can be put on different data points that might be considered as more or less important in order to get a reasonable and plausible modal. If None is given, all data points are considered of the same importance in the computation of the constraint’s standard error. If numpy.ndarray is given, all weights must be positive and all zeros weighted data points won’t contribute to the total constraint’s standard error. At least a single weight point is required to be non-zeros and the weights array will be automatically scaled upon setting such as the the sum of all the weights is equal to the number of data points. scaleFactor (number): A normalization scale factor used to normalize the computed data to the experimental ones. adjustScaleFactor (list, tuple): Used to adjust fit or guess the best scale factor during stochastic engine runtime. It must be a list of exactly three entries. The frequency in number of generated moves of finding the best scale factor. If 0 frequency is given, it means that the scale factor is fixed. The minimum allowed scale factor value. The maximum allowed scale factor value.

NB: If adjustScaleFactor first item (frequency) is 0, the scale factor will remain untouched and the limits minimum and maximum won’t be checked.

experimentalData

Experimental data of the constraint.

dataWeights

Experimental data points weight

multiframeWeight

Get constraint weight towards total in a multiframe system.

multiframePrior

Get constraint multiframe prior array.

scaleFactor

Constraint’s scaleFactor.

adjustScaleFactor

Adjust scale factor tuple.

adjustScaleFactorFrequency

Scale factor adjustment frequency.

adjustScaleFactorMinimum

Scale factor adjustment minimum number allowed.

adjustScaleFactorMaximum

Scale factor adjustment maximum number allowed.

limits

Used data X limits.

limitsIndexStart

Used data start index as calculated from limits.

limitsIndexEnd

Used data end index as calculated from limits.

set_scale_factor(scaleFactor)

Set the scale factor. This method doesn’t allow specifying frames. It will target used frame only.

Parameters: scaleFactor (number): A normalization scale factor used to normalize the computed data to the experimental ones.
set_adjust_scale_factor(adjustScaleFactor)

Set adjust scale factor. This method doesn’t allow specifying frames. It will target used frame only.

Parameters: adjustScaleFactor (list, tuple): Used to adjust fit or guess the best scale factor during stochastic engine runtime. It must be a list of exactly three entries. The frequency in number of generated moves of finding the best scale factor. If 0 frequency is given, it means that the scale factor is fixed. The minimum allowed scale factor value. The maximum allowed scale factor value.
set_experimental_data(experimentalData)

Set the constraint’s experimental data. This method will raise an error if called after adding constraint to stochastic engine.

Parameters: experimentalData (numpy.ndarray, string, list, tuple): Experimental data as numpy.ndarray or string path to load data using numpy.loadtxt method. If list or tuple are given, they will be automatically converted to a numpy array by calling numpy.array(experimentalData). Finally experimental data type will be converted to fullrmc.Globals.FLOAT_TYPE
set_data_weights(dataWeights, frame=None)

Set experimental data points weight. Data weights will be automatically normalized.

Parameters: dataWeights (None, numpy.ndarray): Weights array of the same number of points of experimentalData used in the constraint’s standard error computation. Therefore particular fitting emphasis can be put on different data points that might be considered as more or less important in order to get a reasonable and plausible model. If None is given, all data points are considered of the same importance in the computation of the constraint’s standard error. If numpy.ndarray is given, all weights must be positive and all zeros weighted data points won’t contribute to the total constraint’s standard error. At least a single weight point is required to be non-zeros and the weights array will be automatically scaled upon setting such as the the sum of all the weights is equal to the number of data points. frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes will be targeted. If subframe is given, rest of multiframe subframes will not be targeted.
check_experimental_data(experimentalData)

Checks the constraint’s experimental data This method must be overloaded in all experimental constraint sub-classes.

Parameters: experimentalData (numpy.ndarray): Experimental data numpy.ndarray.
fit_scale_factor(experimentalData, modelData, dataWeights)

The best scale factor value is computed by minimizing $$E=sM$$.

Where:
1. $$E$$ is the experimental data.
2. $$s$$ is the scale factor.
3. $$M$$ is the model constraint data.

This method doesn’t allow specifying frames. It will target used frame only.

Parameters: experimentalData (numpy.ndarray): Experimental data. modelData (numpy.ndarray): Constraint modal data. dataWeights (None, numpy.ndarray): Data points weights to compute the scale factor. If None is given, all data points will be considered as having the same weight. scaleFactor (number): The new scale factor fit value.

NB: This method won’t update the internal scale factor value of the constraint. It always computes the best scale factor given experimental and atomic model data.

get_adjusted_scale_factor(experimentalData, modelData, dataWeights)

Checks if scale factor should be updated according to the given scale factor frequency and engine’s accepted steps. If adjustment is due, a new scale factor will be computed using fit_scale_factor method, otherwise the the constraint’s scale factor will be returned.

Parameters: experimentalData (numpy.ndarray): the experimental data. modelData (numpy.ndarray): the constraint modal data. dataWeights (None, numpy.ndarray): the data points weights to compute the scale factor. If None is given, all data points will be considered as having the same weight. #. scaleFactor (number): Constraint’s scale factor or the new scale factor fit value.

NB: This method WILL NOT UPDATE the internal scale factor value of the constraint.

compute_standard_error(experimentalData, modelData)

Compute the squared deviation between modal computed data and the experimental ones.

$SD = \sum \limits_{i}^{N} W_{i}(Y(X_{i})-F(X_{i}))^{2}$

Where:

$$N$$ is the total number of experimental data points.

$$W_{i}$$ is the data point weight. It becomes equivalent to 1 when dataWeights is set to None.

$$Y(X_{i})$$ is the experimental data point $$X_{i}$$.

$$F(X_{i})$$ is the computed from the model data $$X_{i}$$.

Parameters: experimentalData (numpy.ndarray): Experimental data. modelData (numpy.ndarray): The data to compare with the experimental one and compute the squared deviation. standardError (number): The calculated standard error of the constraint.
get_constraints_properties(frame)

Get a dictionary look up table of constraint’s properties that are needed to plot or export

Parameters: frame (string): frame to pull and build contraint data. It can be a traditional frame, a multiframe or a subframe propertiesLUT (dictionary): properties value look up table. Keys are described herein. Values of keys that start with ‘frames-‘ are a list for all frames. Values of keys that start with ‘weighted-‘ are weighted values for all frames frames-name: list of all frames name. frames-weight: list of all frames weight. frames-number_of_removed_atoms: list of number of removed atoms from each frame. frames-experimental_x: list of numpy array of experimental x data. frames-experimental_y: list of numpy array of experimental y data. frames-output: list of frames dictionary constraint output data frames-model_x: list of numpy array of model x data. frames-shape_array: list of system shape function (numpy array) of all frames. frames-window_function: list of window function (numpy array) of all frames. frames-scale_factor: list of all frames scale factor. frames-standard_error: list of all frames standard error. weighted-output: dictionary of all frames weighted constraint data using ‘frames-weight’ weighted-number_of_removed_atoms: All frames averaged number of removed atoms using ‘frames-weight’ weighted-scale_factor: All frames averaged scale factor using ‘frames-weight’ weighted-standard_error: All frames weighted standard error using ‘frames-weight’
plot(frame=None, axes=None, asMesoscopic=False, intra=True, inter=True, shapeFunc=True, subAdParams={'bottom': None, 'hspace': 0.4, 'left': None, 'right': None, 'top': None, 'wspace': None}, totParams={'color': 'black', 'label': 'total', 'linewidth': 3.0, 'zorder': 1}, expParams={'color': 'red', 'label': 'experimental', 'marker': 'o', 'markersize': 7.5, 'markevery': 1, 'zorder': 0}, noWParams={'color': 'black', 'label': 'total - no window', 'linewidth': 1.0, 'zorder': 1}, shaParams={'color': 'black', 'label': 'shape function', 'linestyle': 'dashed', 'linewidth': 1.0, 'zorder': 2}, parParams={'linewidth': 1.0, 'markersize': 5, 'markevery': 5, 'zorder': 3}, xlabelParams={'size': 10, 'xlabel': 'X'}, ylabelParams={'size': 10, 'ylabel': 'Y'}, xticksParams={'fontsize': 8, 'rotation': 0}, yticksParams={'fontsize': 8, 'rotation': 0}, legendParams={'fontsize': 8, 'frameon': False, 'loc': 'upper right', 'ncol': 2}, titleParams={'fontsize': 10, 'label': '@{frame} (${numberOfRemovedAtoms:.1f}$ $rem.$ $at.$) $Std.Err.={standardError:.3f}$\n$scale$ $factor$=${scaleFactor:.2f}$ - $multiframe$ $weight$=${multiframeWeight:.3f}$ - $used$ $({used})$'}, gridParams=None, show=True, **paramsKwargs)

Plot constraint data. This can be overloaded in children classes.

Parameters: frame (None, string): The frame name to plot. If None, used frame will be plotted. axes (None, matplotlib Axes): matplotlib Axes instance to plot in. If None is given a new plot figure will be created. asMesoscopic (boolean): If given frame is a multiframe is, when true, asMesoscopic considers all frames as a statistical average of all frames in a mesoscopic system. All subframes will be then plotted as a single weighted mesoscopic structure. If asMesocopic is False and given frame is a multiframe given ax will be disregarded intra (boolean): Whether to add intra-molecular pair distribution function features to the plot. inter (boolean): Whether to add inter-molecular pair distribution function features to the plot. shapeFunc (boolean): Whether to add shape function to the plot only when exists. subAdParams (None, dict): matplotlib.artist.Artist.subplots_adjust parameters subplots adjust parameters. totParams (None, dict): constraint total plotting parameters expParams (None, dict): constraint experimental data parameters noWParams (None, dict): constraint total without window parameters shaParams (None, dict): constraint shape function parameters parParams (None, dict): constraint partials parameters xlabelParams (None, dict): matplotlib.axes.Axes.set_xlabel parameters. ylabelParams (None, dict): matplotlib.axes.Axes.set_ylabel parameters. legendParams (None, dict):matplotlib.axes.Axes.legend parameters. xticksParams (None, dict):matplotlib.axes.Axes.set_xticklabels parameters. yticksParams (None, dict):matplotlib.axes.Axes.set_yticklabels parameters. titleParams (None, dict): matplotlib.axes.Axes.set_title parameters gridParams (None, dict): matplotlib.axes.Axes.grid parameters show (boolean): Whether to render and show figure before returning. figure (matplotlib Figure): matplotlib used figure. axes (matplotlib Axes): matplotlib used axes.
plot_multiframe_weights(frame, ax=None, titleFormat='@{frame} [subframes probability distribution]', show=True)

plot multiframe subframes weight distribution histogram

Parameters: frame (string): multiframe name ax (None, matplotlib Axes): matplotlib Axes instance to plot in. If None is given a new plot figure will be created. titleFormat (string): title format. If empty string is given no title will be added to figure axes show (boolean): Whether to render and show figure before returning. figure (matplotlib Figure): matplotlib used figure. axes (matplotlib Axes): matplotlib used axes.
export(fileName, frame=None, format='%12.5f', delimiter='\t', comments='#')

Export constraint data to text file or to an archive of files.

Parameters: fileName (path): full file name and path. frame (None, string): frame name to export data from. If multiframe is given, multiple files will be created with subframe name appended to the end. format (string): string format to export the data. format is as follows (%[flag]width[.precision]specifier) delimiter (string): String or character separating columns. comments (string): String that will be prepended to the header.
class fullrmc.Core.Constraint.SingularConstraint

A singular constraint is a constraint that doesn’t allow multiple instances in the same engine.

is_singular(engine)

Get whether only one instance of this constraint type is present in the stochastic engine. True for only itself found, False for other instance of the same __class__.__name__ or constraintId.

Parameters: engine (stochastic fullrmc engine): Engine instance. result (boolean): Whether constraint is singular in engine.
assert_singular(engine)

Checks whether only one instance of this constraint type is present in the stochastic engine. Raises Exception if multiple instances are present.

class fullrmc.Core.Constraint.RigidConstraint(rejectProbability)

A rigid constraint is a constraint that doesn’t count into the total standard error of the stochastic Engine. But it’s internal standard error must monotonously decrease or remain the same from one engine step to another. If standard error of an rigid constraint increases the step will be rejected even before engine’s new standardError get computed.

Parameters: rejectProbability (Number): Rejecting probability of all steps where standard error increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standard error increases or not.
rejectProbability

Rejection probability.

set_reject_probability(rejectProbability)

Set the rejection probability. This method doesn’t allow specifying frames. It will target used frame only.

Parameters: rejectProbability (Number): rejecting probability of all steps where standard error increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standard error increases or not.
should_step_get_rejected(standardError)

Given a standard error, return whether to keep or reject new standard error according to the constraint reject probability.

Parameters: #. standardError (number): The standard error to compare with the Constraint standard error result (boolean): True to reject step, False to accept
should_step_get_accepted(standardError)

Given a standard error, return whether to keep or reject new standard error according to the constraint reject probability.

Parameters: standardError (number): The standard error to compare with the Constraint standard error result (boolean): True to accept step, False to reject
fullrmc.Core.Constraint.randfloat()

random() -> x in the interval [0, 1).

# fullrmc.Constraints package¶

## Collection¶

Collection of methods and classes definition useful for constraints computation

class fullrmc.Constraints.Collection.ShapeFunction(engine, weighting='atomicNumber', qmin=0.001, qmax=1, dq=0.005, rmin=0.0, rmax=100, dr=1)

Bases: object

Shape function used to correct for particle shape. The shape function is subtracted from the total G(r) of g(r). It must be used when non-periodic boundary conditions are used to take into account the atomic density drop and to correct for the $$\rho_{0}$$ approximation.

Parameters: engine (Engine): The fitting engine. weighting (string): The elements weighting. qmin (number): The minimum reciprocal distance q in $$\AA^{-1}$$ considered to compute the shape function. qmax (number): The maximum reciprocal distance q in $$\AA^{-1}$$ considered to compute the shape function. dq (number): The reciprocal distance bin size in $$\AA^{-1}$$ considered to compute the shape function. rmin (number): The minimum distance in $$\AA$$ considered upon building the histogram prior to computing the shape function. rmax (number): The maximum distance in $$\AA$$ considered upon building the histogram prior to computing the shape function. dr (number): The bin size in $$\AA$$ considered upon building the histogram prior to computing the shape function.

N.B: tweak qmax as small as possible to reduce the wriggles …

get_Gr_shape_function(rValues, compute=True)

Get shape function of G(r) used in a PairDistributionConstraint.

Parameters: rValues (numpy.ndarray): The r values array. compute (boolean): whether to recompute shape function reciprocal data. shapeFunction (numpy.ndarray): The compute shape function.
get_gr_shape_function(rValues, compute=True)

Get shape function of g(r) used in a PairCorrelationConstraint.

Parameters: rValues (numpy.ndarray): The r values array. compute (boolean): whether to recompute shape function reciprocal data. shapeFunction (numpy.ndarray): The compute shape function.

## DistanceConstraints¶

DistanceConstraints contains classes for all constraints related to distances between atoms.

class fullrmc.Constraints.DistanceConstraints.InterMolecularDistanceConstraint(defaultDistance=1.5, typeDefinition='element', pairsDistanceDefinition=None, flexible=True, rejectProbability=1)

Bases: fullrmc.Constraints.DistanceConstraints._MolecularDistanceConstraint

Its controls the inter-molecular distances between atoms.

Parameters: defaultDistance (number): The minimum distance allowed set by default for all atoms type. typeDefinition (string): Can be either ‘element’ or ‘name’. Sets the rules about how to differentiate between atoms and how to parse pairsLimits. pairsDistanceDefinition (None, list, set, tuple): The minimum distance set to every pair of elements. A list of tuples must be given, all missing pairs will get automatically assigned the given defaultMinimumDistance value. First defined elements pair distance will cancel all redundant. If None is given all pairs will be automatically generated and assigned the given defaultMinimumDistance value. e.g. [('h','h',1.5), ('h','c',2.015), ...]  flexible (boolean): Whether to allow atoms to break constraint’s definition under the condition of decreasing total standardError of the constraint. If flexible is set to False, atoms will never be allowed to cross from above to below minimum allowed distance. Even if the later will decrease some other unsatisfying atoms distances, and therefore the total standardError of the constraint. rejectProbability (Number): rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.DistanceConstraints import InterMolecularDistanceConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
EMD = InterMolecularDistanceConstraint()

# create definition
EMD.set_pairs_distance([('Si','Si',1.75), ('O','O',1.10), ('Si','O',1.30)])

defaultDistance

Default minimum distance.

pairsDistanceDefinition

Pairs distance definition.

pairsDistance

Pairs distance dictionary.

flexible

Flexible flag.

lowerLimitArray

Lower limit array used in distances calculation. for InterMolecularDistanceConstraint it’s always a numpy.zeros array

upperLimitArray

Upper limit array used in distances calculation. for InterMolecularDistanceConstraint it’s the minimum distance allowed between pair of intermolecular atoms.

typePairs

Atom’s type pairs sorted list.

typeDefinition

Atom’s type definition.

types

Atom’s type set.

allTypes

All atoms type.

numberOfTypes

Number of defined atom types in the configuration.

typesIndex

Type indexes list.

numberOfAtomsPerType

Number of atoms per type dict.

listen(message, argument=None)

listen to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_flexible(flexible)

Set flexible flag.

Parameters: flexible (boolean): Whether to allow atoms to break constraints definition under the condition of decreasing total standardError. If flexible is set to False, atoms will never be allowed to cross from above to below minimum allowed distance. Even if the later will decrease some other unsatisfying atoms distances, and therefore the total standardError of the constraint.
set_default_distance(defaultDistance)

Sets the default intermolecular minimum distance.

Parameters: defaultDistance (number): The default minimum distance.
set_type_definition(typeDefinition, pairsDistanceDefinition=None)

Alias to set_pairs_distance used when typeDefinition needs to be re-defined.

Parameters: typeDefinition (string): Can be either ‘element’ or ‘name’. Sets the rules about how to differentiate between atoms and how to parse pairsLimits. pairsDistanceDefinition (None, list, set, tuple): Minimum distance to every pair of elements. If None is given, the already defined pairsDistanceDefinition will be used and passed to set_pairs_distance method.
set_pairs_distance(pairsDistanceDefinition)

Set the pairs intermolecular minimum distance.

Parameters: pairsDistanceDefinition (None, list, set, tuple): The minimum distance to every pair of elements. A list of tuples must be given, all missing pairs will get automatically assigned the given default minimum distance value. First defined elements pair distance will cancel all redundant ones. If None is given, all pairs will be automatically generated and assigned the given defaultMinimumDistance value. e.g. [('h','h',1.5), ('h','c',2.015), ...] 
should_step_get_rejected(standardError)

Given a standardError, return whether to keep or reject new standardError according to the constraint rejectProbability. In addition, if flexible flag is set to True, total number of atoms not satisfying constraints definition must be decreasing or at least remain the same.

Parameters: standardError (number): Standard error to compare with Constraint’s standard error. result (boolean): True to reject step, False to accept.
compute_standard_error(data)

Compute the standard error (stdErr) of data not satisfying constraint’s conditions.

$stdErr = \sum \limits_{i}^{N} \sum \limits_{i+1}^{N} \left| d_{ij}-D_{ij}) \right| \int_{0}^{D_{ij}} \delta(x-d_{ij}) dx$

Where:

$$N$$ is the total number of atoms in the system.

$$D_{ij}$$ is the distance constraint set for atoms pair (i,j).

$$d_{ij}$$ is the distance between atom i and atom j.

$$\delta$$ is the Dirac delta function.

$$\int_{0}^{D_{ij}} \delta(x-d_{ij}) dx$$ is equal to 1 if $$0 \leqslant d_{ij} \leqslant D_{ij}$$ and 0 elsewhere.

Parameters: data (dict): data used to compute standard error. standardError (number): The calculated standardError.
get_constraint_value()

Get constraint’s formatted dictionary data.

Returns: data (dictionary): Formatted dictionary data. Keys are type pairs and values constraint data.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint before move is executed

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint’s data after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if atom given its its was amputated.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and sets constraints data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Atom’s relative index as a numpy array of a single element.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): No used here. relativeIndex (numpy.ndarray): Not used here.
plot(inBarParams={'color': '#0066ff', 'label': 'inbound', 'width': 0.6}, outBarParams={'color': '#d62728', 'label': 'outbound', 'width': 0.6}, txtParams={'color': 'black', 'fontsize': 8, 'horizontalalignment': 'center', 'rotation': 90, 'verticalalignment': 'center'}, xlabelParams={'size': 10, 'xlabel': 'Type pairs'}, ylabelParams={'size': 10, 'ylabel': 'Number of pairs'}, xticksParams={'fontsize': 8, 'rotation': 45}, **kwargs)

Alias to Constraint.plot with additional parameters

1. dataParams (None, dict): modified constraint data plotting parameters
2. barParams (None, dict): matplotlib.axes.Axes.bar parameters
3. txtParams (None, dict): matplotlib.axes.Axes.text parameters
4. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
5. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
6. xticksParams (None, dict): modified matplotlib.axes.Axes.set_xticklabels parameters.
7. titleParams (None, dict): title format.
8. show (boolean): Whether to render and show figure before returning.
export(fileName, frame=None, format='%s', delimiter='\t', comments='#')

Export constraint data to text file or to an archive of files.

Parameters: fileName (path): full file name and path. frame (None, string): frame name to export data from. If multiframe is given, multiple files will be created with subframe name appended to the end. format (string): string format to export the data. format is as follows (%[flag]width[.precision]specifier) delimiter (string): String or character separating columns. comments (string): String that will be prepended to the header.
class fullrmc.Constraints.DistanceConstraints.IntraMolecularDistanceConstraint(defaultDistance=1.5, typeDefinition='name', pairsDistanceDefinition=None, flexible=True, rejectProbability=1)

Bases: fullrmc.Constraints.DistanceConstraints._MolecularDistanceConstraint

Its controls the intra-molecular distances between atoms.

Parameters: defaultDistance (number): The minimum distance allowed set by default for all atoms type. typeDefinition (string): Can be either ‘element’ or ‘name’. Sets the rules about how to differentiate between atoms and how to parse pairsLimits. pairsDistanceDefinition (None, list, set, tuple): The minimum distance set to every pair of elements. A list of tuples must be given, all missing pairs will get automatically assigned the given default minimum distance value. First defined elements pair distance will cancel all redundant. If None is given all pairs will be automatically generated and assigned the given default minimum distance value. e.g. [('h','h',1.5), ('h','c',2.015), ...]  flexible (boolean): Whether to allow atoms to break constraint’s definition under the condition of decreasing total standardError of the constraint. If flexible is set to False, atoms will never be allowed to cross from above to below minimum allowed distance. Even if the later will decrease some other unsatisfying atoms distances, and therefore the total standardError of the constraint. rejectProbability (Number): rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.DistanceConstraints import IntraMolecularDistanceConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
EMD = IntraMolecularDistanceConstraint()

# create definition
EMD.set_pairs_distance([('Si','Si',1.75), ('O','O',1.10), ('Si','O',1.30)])

defaultDistance

Default minimum distance.

pairsDistanceDefinition

Pairs distance definition.

pairsDistance

Pairs distance dictionary.

flexible

Flexible flag.

lowerLimitArray

Lower limit array used in distances calculation. for InterMolecularDistanceConstraint it’s always a numpy.zeros array

upperLimitArray

Upper limit array used in distances calculation. for InterMolecularDistanceConstraint it’s the minimum distance allowed between pair of intermolecular atoms.

typePairs

Atom’s type pairs sorted list.

typeDefinition

Atom’s type definition.

types

Atom’s type set.

allTypes

All atoms type.

numberOfTypes

Number of defined atom types in the configuration.

typesIndex

Type indexes list.

numberOfAtomsPerType

Number of atoms per type dict.

listen(message, argument=None)

listen to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_flexible(flexible)

Set flexible flag.

Parameters: flexible (boolean): Whether to allow atoms to break constraints definition under the condition of decreasing total standardError. If flexible is set to False, atoms will never be allowed to cross from above to below minimum allowed distance. Even if the later will decrease some other unsatisfying atoms distances, and therefore the total standardError of the constraint.
set_default_distance(defaultDistance)

Sets the default intermolecular minimum distance.

Parameters: defaultDistance (number): The default minimum distance.
set_type_definition(typeDefinition, pairsDistanceDefinition=None)

Alias to set_pairs_distance used when typeDefinition needs to be re-defined.

Parameters: typeDefinition (string): Can be either ‘element’ or ‘name’. Sets the rules about how to differentiate between atoms and how to parse pairsLimits. pairsDistanceDefinition (None, list, set, tuple): Minimum distance to every pair of elements. If None is given, the already defined pairsDistanceDefinition will be used and passed to set_pairs_distance method.
set_pairs_distance(pairsDistanceDefinition)

Set the pairs intermolecular minimum distance.

Parameters: pairsDistanceDefinition (None, list, set, tuple): The minimum distance to every pair of elements. A list of tuples must be given, all missing pairs will get automatically assigned the given default minimum distance value. First defined elements pair distance will cancel all redundant ones. If None is given, all pairs will be automatically generated and assigned the given defaultMinimumDistance value. e.g. [('h','h',1.5), ('h','c',2.015), ...] 
should_step_get_rejected(standardError)

Given a standardError, return whether to keep or reject new standardError according to the constraint rejectProbability. In addition, if flexible flag is set to True, total number of atoms not satisfying constraints definition must be decreasing or at least remain the same.

Parameters: standardError (number): Standard error to compare with Constraint’s standard error. result (boolean): True to reject step, False to accept.
compute_standard_error(data)

Compute the standard error (stdErr) of data not satisfying constraint’s conditions.

$stdErr = \sum \limits_{i}^{N} \sum \limits_{i+1}^{N} \left| d_{ij}-D_{ij}) \right| \int_{0}^{D_{ij}} \delta(x-d_{ij}) dx$

Where:

$$N$$ is the total number of atoms in the system.

$$D_{ij}$$ is the distance constraint set for atoms pair (i,j).

$$d_{ij}$$ is the distance between atom i and atom j.

$$\delta$$ is the Dirac delta function.

$$\int_{0}^{D_{ij}} \delta(x-d_{ij}) dx$$ is equal to 1 if $$0 \leqslant d_{ij} \leqslant D_{ij}$$ and 0 elsewhere.

Parameters: data (dict): data used to compute standard error. standardError (number): The calculated standardError.
get_constraint_value()

Get constraint’s formatted dictionary data.

Returns: data (dictionary): Formatted dictionary data. Keys are type pairs and values constraint data.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint before move is executed

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint’s data after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if atom given its its was amputated.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and sets constraints data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Atom’s relative index as a numpy array of a single element.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): No used here. relativeIndex (numpy.ndarray): Not used here.
plot(inBarParams={'color': '#0066ff', 'label': 'inbound', 'width': 0.6}, outBarParams={'color': '#d62728', 'label': 'outbound', 'width': 0.6}, txtParams={'color': 'black', 'fontsize': 8, 'horizontalalignment': 'center', 'rotation': 90, 'verticalalignment': 'center'}, xlabelParams={'size': 10, 'xlabel': 'Type pairs'}, ylabelParams={'size': 10, 'ylabel': 'Number of pairs'}, xticksParams={'fontsize': 8, 'rotation': 45}, **kwargs)

Alias to Constraint.plot with additional parameters

1. dataParams (None, dict): modified constraint data plotting parameters
2. barParams (None, dict): matplotlib.axes.Axes.bar parameters
3. txtParams (None, dict): matplotlib.axes.Axes.text parameters
4. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
5. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
6. xticksParams (None, dict): modified matplotlib.axes.Axes.set_xticklabels parameters.
7. titleParams (None, dict): title format.
8. show (boolean): Whether to render and show figure before returning.
export(fileName, frame=None, format='%s', delimiter='\t', comments='#')

Export constraint data to text file or to an archive of files.

Parameters: fileName (path): full file name and path. frame (None, string): frame name to export data from. If multiframe is given, multiple files will be created with subframe name appended to the end. format (string): string format to export the data. format is as follows (%[flag]width[.precision]specifier) delimiter (string): String or character separating columns. comments (string): String that will be prepended to the header.

## CoordinationConstraints¶

AtomicCoordinationConstraints contains classes for all constraints related to coordination number in spherical shells around atoms.

class fullrmc.Constraints.AtomicCoordinationConstraints.AtomicCoordinationNumberConstraint(rejectProbability=1)

It’s a rigid constraint that controls the coordination number of atoms.

Parameters: rejectProbability (Number): rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.AtomicCoordinationConstraints import AtomicCoordinationNumberConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
ACNC = AtomicCoordinationNumberConstraint()

# create definition
ACNC.set_coordination_number_definition( [ ('Al','Cl',1.5, 2.5, 2, 2),
('Al','S', 2.5, 3.0, 2, 2)] )

coordNumDef

Copy of coordination number definition dictionary

coordinationNumberDefinition

alias to coordinationNumberDefinition

coresIndexes

List of coordination number core atoms index array.

shellsIndexes

List of coordination number shell atoms index array.

numberOfCores

Array of number of core atoms

lowerShells

Array of lower shells distance.

upperShells

Array of upper shells distance.

minAtoms

Array of minimum number of atoms in a shell.

maxAtoms

Array of maximum number of atoms in a shell.

weights

Shells weight which count in the computation of standard error.

data

Coordination number constraint data.

asCoreDefIdxs

List of arrays where each element is pointing to a coordination number definition where the atom is a core.

inShellDefIdxs

List of arrays where each element is pointing to a coordination number definition where the atom is in a shell.

listen(message, argument=None)

listen to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_coordination_number_definition(coordNumDef)

Set the coordination number definition.

Parameters: coordNumDef (None, list, tuple): Coordination number definition. It must be None, list or tuple where every element is a list or a tuple of exactly 6 items and an optional 7th item for weight. core atoms: Can be any of the following: string: indicating atomic element. dictionary: Key as atomic attribute among (element, name) and value is the attribute value. list, tuple, set, numpy.ndarray: core atoms index. in shell atoms: Can be any of the following: string: indicating atomic element. dictionary: Key as atomic attribute among (element, name) and value is the attribute value. list, tuple, set, numpy.ndarray: in shell atoms index Lower distance limit of the coordination shell. Upper distance limit of the coordination shell. $$N_{min}$$ : minimum number of neighbours in the shell. $$N_{max}$$ : maximum number of neighbours in the shell. $$W_{i}$$ : weight contribution to the standard error, this is optional, if not given it is set automatically to 1.0. e.g. [ ('Ti','Ti', 2.5, 3.5, 5, 7.1, 1), ('Ni','Ti', 2.2, 3.1, 7.2, 9.7, 100), ...] [ ({'element':'Ti'},'Ti', 2.5, 3.5, 5, 7.1, 0.1), ...] [ ({'name':'au'},'Au', 2.5, 3.5, 4.1, 6.3), ...] [ ({'name':'Ni'},{'element':'Ti'}, 2.2, 3.1, 7, 9), ...] [ ('Ti',range(100,500), 2.2, 3.1, 7, 9), ...] [ ([0,10,11,15,1000],{'name':'Ti'}, 2.2, 3.1, 7, 9, 5), ...] 
compute_standard_error(data)

Compute the standard error (StdErr) of data not satisfying constraint’s conditions.

$StdErr = \sum \limits_{i}^{S} Dev_{i}$
$\begin{split}Dev_{i}=\begin{cases} W_{i}*( N_{min,i}-\overline{CN_{i}} ), & \text{if \overline{CN_{i}}<N_{min,i}}.\\ W_{i}*( \overline{CN_{i}}-N_{max,i} ), & \text{if \overline{CN_{i}}>N_{max,i}}.\\ 0 , & \text{if N_{min,i}<=\overline{CN_{i}}<=N_{max,i}} \end{cases}\end{split}$

Where:

$$S$$ is the total number of defined coordination number shells.

$$W_{i}$$ is the defined weight of coordination number shell i.

$$Dev_{i}$$ is the standard deviation of the coordination number in shell definition i.

$$\overline{CN_{i}}$$ is the mean coordination number value in shell definition i.

$$N_{min,i}$$ is the defined minimum number of neighbours in shell definition i.

$$N_{max,i}$$ is the defined maximum number of neighbours in shell definition i.

Parameters: data (numpy.array): The constraint value data to compute standardError. standardError (number): The calculated standardError of the constraint.
get_constraint_value()

Get constraint’s data.

Returns: data (numpy.array): The constraint value data
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint’s data before move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint’s data after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move.

Parameters: realIndexes (numpy.ndarray): not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move.

Parameters: realIndexes (numpy.ndarray): not used here. relativeIndexes (numpy.ndarray): Not used here.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if atom given its its was amputated.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and sets constraints data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Atom’s relative index as a numpy array of a single element.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here
plot(dataParams={'color': '#ffcc00', 'label': 'mean coord num', 'linewidth': 0, 'marker': 'o', 'markersize': 20, 'markevery': 1}, barParams={'color': '#99ccff', 'label': 'boundaries', 'width': 0.6}, txtParams={'color': 'black', 'fontsize': 8, 'horizontalalignment': 'center', 'rotation': 90, 'verticalalignment': 'center'}, xlabelParams={'size': 10, 'xlabel': 'Core-Shell atoms'}, ylabelParams={'size': 10, 'ylabel': 'Coordination number'}, xticksParams={'fontsize': 8, 'rotation': 45}, titleParams={'fontsize': 8, 'label': '@{frame} (${numberOfRemovedAtoms:.1f}$ $rem.$ $at.$) $Std.Err.={standardError:.3f}$'}, **kwargs)

Alias to Constraint.plot with additional parameters

1. dataParams (None, dict): modified constraint data plotting parameters
2. barParams (None, dict): matplotlib.axes.Axes.bar parameters
3. txtParams (None, dict): matplotlib.axes.Axes.text parameters
4. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
5. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
6. xticksParams (None, dict): modified matplotlib.axes.Axes.set_xticklabels parameters.
7. titleParams (None, dict): title format.
8. show (boolean): Whether to render and show figure before returning.

## BondConstraints¶

BondConstraints contains classes for all constraints related to bond length between atoms.

class fullrmc.Constraints.BondConstraints.BondConstraint(rejectProbability=1)

Controls the bond’s length defined between two atoms.

 Bond sketch defined between two atoms.
Parameters: rejectProbability (Number): rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
## Water (H2O) molecule sketch
##
##              O
##            /   \
##         /   H2O   \
##       H1           H2

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.BondConstraints import BondConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
BC = BondConstraint()

# define intra-molecular bonds
BC.create_bonds_by_definition( bondsDefinition={"H2O": [ ('O','H1', 0.88, 1.02),
('O','H2', 0.88, 1.02) ]} )

bondsList

List of defined bonds

bondsDefinition

bonds definition copy if bonds are defined as such

bonds

Bonds dictionary map of every and each atom

listen(message, argument=None)

Listens to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_bonds(bondsList, tform=True)

Sets bonds dictionary by parsing bondsList list.

Parameters: bondsList (None, list): Bonds definition list. If None is given no bonds are defined. Otherwise it can be of any of the following two forms: tuples format: every item must be a list or tuple of four items. First atom index forming the bond. Second atom index forming the bond. Lower limit or the minimum bond length allowed. Upper limit or the maximum bond length allowed. four vectors format: List of exaclty four lists or numpy.arrays of the same length. List contains the first atoms index forming the bond. List contains the second atoms index forming the bond. List containing the lower limit or the minimum bond length allowed. List containing the upper limit or the maximum bond length allowed. tform (boolean): set whether given bondsList follows tuples format, If not then it must follow the four vectors one.
create_bonds_by_definition(bondsDefinition)

Creates bondsList using bonds definition. Calls set_bonds(bondsList) and generates bonds attribute.

Parameters: bondsDefinition (dict): The bonds definition. Every key must be a molecule’s name. Every key value must be a list of bonds definitions. Every bond definition is a list of four items where: Name of the first atom forming the bond. Name of the second atom forming the bond. Lower limit or the minimum bond length allowed. Upper limit or the maximum bond length allowed. e.g. (Carbon tetrachloride): bondsDefinition={"CCL4": [('C','CL1' , 1.55, 1.95), ('C','CL2' , 1.55, 1.95), ('C','CL3' , 1.55, 1.95), ('C','CL4' , 1.55, 1.95) ] } 
compute_standard_error(data)

Compute the standard error (StdErr) of data not satisfying constraint conditions.

$StdErr = \sum \limits_{i}^{C} ( \beta_{i} - \beta_{i}^{min} ) ^{2} \int_{0}^{\beta_{i}^{min}} \delta(\beta-\beta_{i}) d \beta + ( \beta_{i} - \beta_{i}^{max} ) ^{2} \int_{\beta_{i}^{max}}^{\infty} \delta(\beta-\beta_{i}) d \beta$

Where:

$$C$$ is the total number of defined bonds constraints.

$$\beta_{i}^{min}$$ is the bond constraint lower limit set for constraint i.

$$\beta_{i}^{max}$$ is the bond constraint upper limit set for constraint i.

$$\beta_{i}$$ is the bond length computed for constraint i.

$$\delta$$ is the Dirac delta function.

$$\int_{0}^{\beta_{i}^{min}} \delta(\beta-\beta_{i}) d \beta$$ is equal to 1 if $$0 \leqslant \beta_{i} \leqslant \beta_{i}^{min}$$ and 0 elsewhere.

$$\int_{\beta_{i}^{max}}^{\pi} \delta(\beta-\beta_{i}) d \beta$$ is equal to 1 if $$\beta_{i}^{max} \leqslant \beta_{i} \leqslant \infty$$ and 0 elsewhere.

Parameters: data (object): Data to compute standardError. #. standardError (number): The calculated standardError of the given.
get_constraint_value()

Get constraint’s data.

Returns: data (numpy.array): The constraint value data
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint’s data before move is executed.

Parameters: realIndexes (numpy.ndarray): Group atoms index the move will be applied to. relativeIndexes (numpy.ndarray): Not used here.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint after move is executed

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if atom given its its was amputated.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and sets constraints data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Not used here.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
plot(spacing=0.1, numberOfTicks=3, nbins=20, barsRelativeWidth=0.95, splitBy=None, stackHorizontal=True, colorCodeXticksLabels=True, xlabelParams={'size': 10, 'xlabel': '$r(\\AA)$'}, ylabelParams={'size': 10, 'ylabel': 'number'}, limitsParams={'color': None, 'linestyle': '--', 'linewidth': 1.0}, **kwargs)

Alias to Constraint.plot with additional parameters

1. spacing (float): spacing between definitions histgrams
2. numberOfTicks (integer): number of ticks per definition histogram
3. nbins (integer): number of bins per definition histogram
4. barsRelativeWidth (float): histogram bar relative width >0 and <1
5. splitBy (None, string): Split definition histograms by atom element, name or merely distance. accepts None, ‘element’, ‘name’
6. stackHorizontal (boolean): whether to stack definition plots horizontally or veritcally
7. colorCodeXticksLabels (boolean): whether to color code x ticks per definition color
8. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
9. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
10. titleParams (None, dict): axes title parameters

## AngleConstraints¶

AngleConstraints contains classes for all constraints related angles between atoms.

class fullrmc.Constraints.AngleConstraints.BondsAngleConstraint(rejectProbability=1)

Controls angle defined between 3 defined atoms, a first atom called central and the remain two called left and right.

 Angle sketch defined between three atoms.
Parameters: rejectProbability (Number): Rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
## Methane (CH4) molecule sketch
##
##              H4
##              |
##              |
##           _- C -_
##        H1-  /    -_
##            /       H3
##           H2

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.AngleConstraints import BondsAngleConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
BAC = BondsAngleConstraint()

# define intra-molecular angles
BAC.create_angles_by_definition( anglesDefinition={"CH4": [ ('C','H1','H2', 100, 120),
('C','H2','H3', 100, 120),
('C','H3','H4', 100, 120),
('C','H4','H1', 100, 120) ]} )

anglesList

Defined angles list.

anglesDefinition

angles definition copy if angles are defined as such

angles

Angles dictionary of every and each atom.

listen(message, argument=None)

Listen to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_angles(anglesList, tform=True)

Sets the angles dictionary by parsing the anglesList. All angles are in degrees.

Parameters: anglesList (list): The angles list definition that can be given in two different formats. tuples format: every item must be a list of five items. Central atom index. Index of the left atom forming the angle (interchangeable with the right atom). Index of the right atom forming the angle (interchangeable with the left atom). Minimum lower limit or the minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit or the maximum angle allowed in degrees which later will be converted to rad. five vectors format: List of exaclty five lists or numpy.arrays or vectors of the same length. List containing central atom indexes. List containing the index of the left atom forming the angle (interchangeable with the right atom). List containing the index of the right atom forming the angle (interchangeable with the left atom). List containing the minimum lower limit or the minimum angle allowed in degrees which later will be converted to rad. List containing the maximum upper limit or the maximum angle allowed in degrees which later will be converted to rad. tform (boolean): set whether given anglesList follows tuples format, If False, then it must follow the five vectors one.
create_angles_by_definition(anglesDefinition)

Creates anglesList using angles definition. Calls set_angles(anglesList) and generates angles attribute.

Parameters: anglesDefinition (dict): Angles definition dictionary. Every key must be a molecule’s name. Every key value must be a list of angles definitions. Every angle definition is a list of five items where: Name of the central atom forming the angle. Name of the left atom forming the angle (interchangeable with the right atom). Name of the right atom forming the angle (interchangeable with the left atom). Minimum lower limit or the minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit or the maximum angle allowed in degrees which later will be converted to rad.
e.g. (Carbon tetrachloride):  anglesDefinition={"CCL4": [('C','CL1','CL2' , 105, 115),
('C','CL2','CL3' , 105, 115),
('C','CL3','CL4' , 105, 115),
('C','CL4','CL1' , 105, 115) ] }

compute_standard_error(data)

Compute the standard error (StdErr) of data not satisfying constraint conditions.

$StdErr = \sum \limits_{i}^{C} ( \theta_{i} - \theta_{i}^{min} ) ^{2} \int_{0}^{\theta_{i}^{min}} \delta(\theta-\theta_{i}) d \theta + ( \theta_{i} - \theta_{i}^{max} ) ^{2} \int_{\theta_{i}^{max}}^{\pi} \delta(\theta-\theta_{i}) d \theta$

Where:

$$C$$ is the total number of defined angles constraints.

$$\theta_{i}^{min}$$ is the angle constraint lower limit set for constraint i.

$$\theta_{i}^{max}$$ is the angle constraint upper limit set for constraint i.

$$\theta_{i}$$ is the angle computed for constraint i.

$$\delta$$ is the Dirac delta function.

$$\int_{0}^{\theta_{i}^{min}} \delta(\theta-\theta_{i}) d \theta$$ is equal to 1 if $$0 \leqslant \theta_{i} \leqslant \theta_{i}^{min}$$ and 0 elsewhere.

$$\int_{\theta_{i}^{max}}^{\pi} \delta(\theta-\theta_{i}) d \theta$$ is equal to 1 if $$\theta_{i}^{max} \leqslant \theta_{i} \leqslant \pi$$ and 0 elsewhere.

Parameters: data (numpy.array): Constraint’s data to compute standardError. standardError (number): The calculated standardError of the given data.
get_constraint_value()

Get partial Mean Pair Distances (MPD) below the defined minimum distance.

Returns: MPD (dictionary): MPD dictionary, where keys are the element wise intra and inter molecular MPDs and values are the computed MPDs.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint before move is executed.

Parameters: realIndexes (numpy.ndarray): Group atoms index the move will be applied to. relativeIndexes (numpy.ndarray): Not used here.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and set constraint’s data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Not used here.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
plot(spacing=2, numberOfTicks=2, nbins=20, barsRelativeWidth=0.95, splitBy=None, stackHorizontal=True, colorCodeXticksLabels=True, xlabelParams={'size': 10, 'xlabel': '$deg.$'}, ylabelParams={'size': 10, 'ylabel': 'number'}, limitsParams={'color': None, 'linestyle': '--', 'linewidth': 1.0}, **kwargs)

Alias to Constraint.plot with additional parameters

1. spacing (float): spacing between definitions histgrams
2. numberOfTicks (integer): number of ticks per definition histogram
3. nbins (integer): number of bins per definition histogram
4. barsRelativeWidth (float): histogram bar relative width >0 and <1
5. splitBy (None, string): Split definition histograms by atom element, name or merely distance. accepts None, ‘element’, ‘name’
6. stackHorizontal (boolean): whether to stack definition plots horizontally or veritcally
7. colorCodeXticksLabels (boolean): whether to color code x ticks per definition color
8. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
9. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
10. titleParams (None, dict): axes title parameters

## DihedralAngleConstraints¶

ImproperAngleConstraints contains classes for all constraint’s related to improper angles between bonded atoms.

class fullrmc.Constraints.DihedralAngleConstraints.DihedralAngleConstraint(rejectProbability=1)

Dihedral angle is defined between two intersecting planes formed with defined atoms. Dihedral angle constraint can control up to three angle shells at the same times.

 Dihedral angle sketch defined between two planes formed with four atoms.
Parameters: rejectProbability (Number): rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
## Butane (BUT) molecule sketch
##
##       H13  H22  H32  H43
##        |    |    |    |
## H11---C1---C2---C3---C4---H41
##        |    |    |    |
##       H12  H21  H31  H42
##

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.DihedralAngleConstraints import DihedralAngleConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
DAC = DihedralAngleConstraint()

# define intra-molecular dihedral angles
DAC.create_angles_by_definition( anglesDefinition={"BUT": [ ('C1','C2','C3','C4', 40,80, 100,140, 290,330), ] })

anglesList

Improper angles list.

anglesDefinition

angles definition copy if dihedral angles are defined as such

angles

Angles dictionary for every and each atom.

listen(message, argument=None)

Listens to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_angles(anglesList, tform=True)

Sets the angles dictionary by parsing the anglesList list. All angles are in degrees. Dihedral angle can control up to three angle shells at the same times defined using three different lower and upper angle bounds simulating three different dihedral potential energy minimums. Dihedral angles are defined from 0 to 360 degrees. Shell’s lower and upper bound defines a dihedral angle clockwise. Therefore in order to take into considerations the limits at 0 and 360 degrees, lower bound is allowed to be higher than the higher bound.

e.g. (50, 100) is a dihedral shell defined in the angle range between 50 and 100 degrees. But (100, 50) dihedral shell is defined between 100 to 360 degrees and wraps the range from 0 to 100. (50, 100) and (100, 50) are complementary and cover the whole range from 0 to 360 deg.

N.B. Defining three shells boundaries is mandatory. In case fewer than three shells is needed, it suffices to repeat one of the shells boundaries.

e.g. (‘C1’,’C2’,’C3’,’C4’, 40,80, 100,140, 40,80), in the herein definition the last shell is a repetition of the first which means only two shells are defined.

create_angles_by_definition(anglesDefinition)

Creates anglesList using angles definition. Calls set_angles(anglesMap) and generates angles attribute.

Parameters: anglesDefinition (dict): The angles definition. Every key must be a molecule name (residue name in pdb file). Every key value must be a list of angles definitions. Every angle definition is a list of ten items where: Name of the first dihedral atom. Name of the second dihedral atom of the first plane and the first atom of the second plane. Name of the third dihedral atom of the first plane and the second atom of the second plane. Name of the fourth dihderal atom of the second plane. Minimum lower limit of the first shell or the minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit of the first or the maximum angle allowed in degrees which later will be converted to rad. Minimum lower limit of the second shell or the minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit of the second or the maximum angle allowed in degrees which later will be converted to rad. Minimum lower limit of the third shell or the minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit of the third or the maximum angle allowed in degrees which later will be converted to rad.
e.g. (Butane):  anglesDefinition={"BUT": [ ('C1','C2','C3','C4', 40,80, 100,140, 290,330), ] }

compute_standard_error(data)

Compute the standard error (StdErr) of data not satisfying constraint conditions.

$StdErr = \sum \limits_{i}^{C} ( \theta_{i} - \theta_{i}^{min} ) ^{2} \int_{0}^{\theta_{i}^{min}} \delta(\theta-\theta_{i}) d \theta + ( \theta_{i} - \theta_{i}^{max} ) ^{2} \int_{\theta_{i}^{max}}^{\pi} \delta(\theta-\theta_{i}) d \theta$

Where:

$$C$$ is the total number of defined improper angles constraints.

$$\theta_{i}^{min}$$ is the improper angle constraint lower limit set for constraint i.

$$\theta_{i}^{max}$$ is the improper angle constraint upper limit set for constraint i.

$$\theta_{i}$$ is the improper angle computed for constraint i.

$$\delta$$ is the Dirac delta function.

$$\int_{0}^{\theta_{i}^{min}} \delta(\theta-\theta_{i}) d \theta$$ is equal to 1 if $$0 \leqslant \theta_{i} \leqslant \theta_{i}^{min}$$ and 0 elsewhere.

$$\int_{\theta_{i}^{max}}^{\pi} \delta(\theta-\theta_{i}) d \theta$$ is equal to 1 if $$\theta_{i}^{max} \leqslant \theta_{i} \leqslant \pi$$ and 0 elsewhere.

Parameters: data (numpy.array): The constraint value data to compute standardError. standardError (number): The calculated standardError of the constraint.
get_constraint_value()

Get constraint’s data.

Returns: data (numpy.array): The constraint value data
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint’s data before move is executed.

Parameters: realIndexes (numpy.ndarray): Group atoms index the move will be applied to. relativeIndexes (numpy.ndarray): Not used here.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint’s data after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move.

1. realIndexes (numpy.ndarray): Not used here.
2. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and set constraint’s data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Not used here.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
plot(spacing=2, numberOfTicks=3, nbins=20, barsRelativeWidth=0.95, splitBy=None, stackHorizontal=False, colorCodeXticksLabels=True, xlabelParams={'size': 10, 'xlabel': '$deg.$'}, ylabelParams={'size': 10, 'ylabel': 'number'}, limitsParams={'color': None, 'linestyle': None, 'linewidth': 1.0}, **kwargs)

Alias to Constraint.plot with additional parameters

1. spacing (float): spacing between definitions histgrams
2. numberOfTicks (integer): number of ticks per definition histogram
3. nbins (integer): number of bins per definition histogram
4. barsRelativeWidth (float): histogram bar relative width >0 and <1
5. splitBy (None, string): Split definition histograms by atom element, name or merely distance. accepts None, ‘element’, ‘name’
6. stackHorizontal (boolean): whether to stack definition plots horizontally or veritcally
7. colorCodeXticksLabels (boolean): whether to color code x ticks per definition color
8. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
9. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
10. titleParams (None, dict): axes title parameters

## ImproperAngleConstraints¶

ImproperAngleConstraints contains classes for all constraints related to improper angles between atoms.

class fullrmc.Constraints.ImproperAngleConstraints.ImproperAngleConstraint(rejectProbability=1)

Controls the improper angle formed with 4 defined atoms. It’s mainly used to keep the improper atom in the plane defined with three other atoms. The improper vector is defined as the vector from the first atom of the plane to the improper atom. Therefore the improper angle is defined between the improper vector and the plane.

 Improper angle sketch defined between four atoms.
Parameters: rejectProbability (Number): rejecting probability of all steps where standardError increases. It must be between 0 and 1 where 1 means rejecting all steps where standardError increases and 0 means accepting all steps regardless whether standardError increases or not.
## Tetrahydrofuran (THF) molecule sketch
##
##              O
##   H41      /   \      H11
##      \  /         \  /
## H42-- C4    THF     C1 --H12
##        \ MOLECULE  /
##         \         /
##   H31-- C3-------C2 --H21
##        /          \
##     H32            H22
##

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.ImproperAngleConstraints import ImproperAngleConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
IAC = ImproperAngleConstraint()

# define intra-molecular improper angles
IAC.create_angles_by_definition( anglesDefinition={"THF": [ ('C2','O','C1','C4', -15, 15),
('C3','O','C1','C4', -15, 15) ] })

anglesList

Get improper angles list.

anglesDefinition

angles definition copy if improper angles are defined as such

angles

Get angles dictionary for every and each atom.

listen(message, argument=None)

Listens to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_angles(anglesList, tform=True)

Set angles dictionary by parsing anglesList list.

Parameters: anglesList (list): Angles list definition. tuples format: every item must be a list of five items. Improper atom index that must be in the plane. Index of atom ‘O’ considered the origin of the plane. Index of atom ‘x’ used to calculated ‘Ox’ vector. Index of atom ‘y’ used to calculated ‘Oy’ vector. Minimum lower limit or minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit or maximum angle allowed in degrees which later will be converted to rad. six vectors format: every item must be a list of five items. List containing improper atoms index that must be in the plane. List containing index of atoms ‘O’ considered the origin of the plane. List containing index of atoms ‘x’ used to calculated ‘Ox’ vector. List containing index of atom ‘y’ used to calculated ‘Oy’ vector. List containing minimum lower limit or minimum angle allowed in degrees which later will be converted to rad. List containing maximum upper limit or maximum angle allowed in degrees which later will be converted to rad. tform (boolean): Whether given anglesList follows tuples format, If not then it must follow the six vectors one.
create_angles_by_definition(anglesDefinition)

Creates anglesList using angles definition. This calls set_angles(anglesMap) and generates angles attribute. All angles are in degrees.

Parameters: anglesDefinition (dict): Angles definition. Every key must be a molecule name. Every key value must be a list of angles definitions. Every angle definition is a list of five items where: Name of improper atom that must be in the plane. Name of atom ‘O’ considered the origin of the plane. Name of atom ‘x’ used to calculated ‘Ox’ vector. Name of atom ‘y’ used to calculated ‘Oy’ vector. Minimum lower limit or minimum angle allowed in degrees which later will be converted to rad. Maximum upper limit or maximum angle allowed in degrees which later will be converted to rad.
e.g. (Benzene):  anglesDefinition={"BENZ": [('C3','C1','C2','C6', -10, 10),
('C4','C1','C2','C6', -10, 10),
('C5','C1','C2','C6', -10, 10) ] }

compute_standard_error(data)

Compute the standard error (StdErr) of data not satisfying constraint’s conditions.

$StdErr = \sum \limits_{i}^{C} ( \theta_{i} - \theta_{i}^{min} ) ^{2} \int_{0}^{\theta_{i}^{min}} \delta(\theta-\theta_{i}) d \theta + ( \theta_{i} - \theta_{i}^{max} ) ^{2} \int_{\theta_{i}^{max}}^{\pi} \delta(\theta-\theta_{i}) d \theta$

Where:

$$C$$ is the total number of defined improper angles constraints.

$$\theta_{i}^{min}$$ is the improper angle constraint lower limit set for constraint i.

$$\theta_{i}^{max}$$ is the improper angle constraint upper limit set for constraint i.

$$\theta_{i}$$ is the improper angle computed for constraint i.

$$\delta$$ is the Dirac delta function.

$$\int_{0}^{\theta_{i}^{min}} \delta(\theta-\theta_{i}) d \theta$$ is equal to 1 if $$0 \leqslant \theta_{i} \leqslant \theta_{i}^{min}$$ and 0 elsewhere.

$$\int_{\theta_{i}^{max}}^{\pi} \delta(\theta-\theta_{i}) d \theta$$ is equal to 1 if $$\theta_{i}^{max} \leqslant \theta_{i} \leqslant \pi$$ and 0 elsewhere.

Parameters: data (numpy.array): data to compute standardError. standardError (number): computed standardError of given data.
get_constraint_value()

get constraint’s data value.

Returns: data (dictionary): constraint data.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint’s data before move is executed.

Parameters: realIndexes (numpy.ndarray): Group atoms index the move will be applied to. relativeIndexes (numpy.ndarray): Not used here.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint’s data after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
accept_amputation(realIndex, relativeIndex)

Accept amputation of atom and sets constraint’s data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Not used here.
reject_amputation(realIndex, relativeIndex)

Reject amputation of atom.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
plot(spacing=2, numberOfTicks=2, nbins=20, barsRelativeWidth=0.95, splitBy=None, stackHorizontal=True, colorCodeXticksLabels=True, xlabelParams={'size': 10, 'xlabel': '$deg.$'}, ylabelParams={'size': 10, 'ylabel': 'number'}, limitsParams={'color': None, 'linestyle': '--', 'linewidth': 1.0}, **kwargs)

Alias to Constraint.plot with additional parameters

1. spacing (float): spacing between definitions histgrams
2. numberOfTicks (integer): number of ticks per definition histogram
3. nbins (integer): number of bins per definition histogram
4. barsRelativeWidth (float): histogram bar relative width >0 and <1
5. splitBy (None, string): Split definition histograms by atom element, name or merely distance. accepts None, ‘element’, ‘name’
6. stackHorizontal (boolean): whether to stack definition plots horizontally or veritcally
7. colorCodeXticksLabels (boolean): whether to color code x ticks per definition color
8. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
9. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
10. titleParams (None, dict): axes title parameters

## PairDistributionConstraints¶

PairDistributionConstraints contains classes for all constraints related to experimental pair distribution functions.

class fullrmc.Constraints.PairDistributionConstraints.PairDistributionConstraint(experimentalData, dataWeights=None, weighting='atomicNumber', atomsWeight=None, scaleFactor=1.0, adjustScaleFactor=(0, 0.8, 1.2), shapeFuncParams=None, windowFunction=None, limits=None)

Controls the total reduced pair distribution function (pdf) of atomic configuration noted as G(r). The pair distribution function is directly calculated from powder diffraction experimental data. It is obtained from the experimentally determined total-scattering structure function S(Q), by a Sine Fourier transform according to.

\begin{align}\begin{aligned}G(r) = \frac{2}{\pi} \int_{0}^{\infty} Q [S(Q)-1]sin(Qr)dQ \\S(Q) = 1+ \frac{1}{Q} \int_{0}^{\infty} G(r) sin(Qr) dr\end{aligned}\end{align}

Theoretically G(r) oscillates about zero. Also $$G(r) \rightarrow 0$$ when $$r \rightarrow \infty$$ and $$G(r) \rightarrow 0$$ when $$r \rightarrow 0$$ with a slope of $$-4\pi\rho_{0}$$ where $$\rho_{0}$$ is the number density of the material.

Model wise, G(r) is computed after calculating the so called Pair Correlation Function noted as g(r). The relation between G(r) and g(r) is given by

$G(r) = 4 \pi r (\rho_{r} - \rho_{0}) = 4 \pi \rho_{0} r (g(r)-1) = \frac{R(r)}{r} - 4 \pi r \rho_{0}$

$$\rho_{r}$$ is the number density fluctuation at distance $$r$$. The computation of g(r) is straightforward from an atomistic model and it is given by $$g(r)=\rho_{r} / \rho_{0}$$.

The radial distribution function noted $$R(r)$$ is a very important function because it describes directly the system’s structure. $$R(r)dr$$ gives the number of atoms in an annulus of thickness dr at distance r from another atom. Therefore, the coordination number, or the number of neighbors within the distances interval $$[a,b]$$ is given by $$\int_{a}^{b} R(r) dr$$

Finally, g(r) is calculated after binning all pair atomic distances into a weighted histograms of values $$n(r)$$ from which local number densities are computed as the following:

$g(r) = \sum \limits_{i,j}^{N} w_{i,j} \frac{\rho_{i,j}(r)}{\rho_{0}} = \sum \limits_{i,j}^{N} w_{i,j} \frac{n_{i,j}(r) / v(r)}{N_{i,j} / V}$

Where:

$$Q$$ is the momentum transfer.

$$r$$ is the distance between two atoms.

$$\rho_{i,j}(r)$$ is the pair density function of atoms i and j.

$$\rho_{0}$$ is the average number density of the system.

$$w_{i,j}$$ is the relative weighting of atom types i and j.

$$R(r)$$ is the radial distribution function (rdf).

$$N$$ is the total number of atoms.

$$V$$ is the volume of the system.

$$n_{i,j}(r)$$ is the number of atoms i neighbouring j at a distance r.

$$v(r)$$ is the annulus volume at distance r and of thickness dr.

$$N_{i,j}$$ is the total number of atoms i and j in the system.

Parameters: experimentalData (numpy.ndarray, string): Experimental data as numpy.ndarray or string path to load data using numpy.loadtxt. dataWeights (None, numpy.ndarray): Weights array of the same number of points of experimentalData used in the constraint’s standard error computation. Therefore particular fitting emphasis can be put on different data points that might be considered as more or less important in order to get a reasonable and plausible modal. If None is given, all data points are considered of the same importance in the computation of the constraint’s standard error. If numpy.ndarray is given, all weights must be positive and all zeros weighted data points won’t contribute to the total constraint’s standard error. At least a single weight point is required to be non-zeros and the weights array will be automatically scaled upon setting such as the the sum of all the weights is equal to the number of data points. weighting (string): The elements weighting scheme. It must be any atomic attribute (atomicNumber, neutronCohb, neutronIncohb, neutronCohXs, neutronIncohXs, atomicWeight, covalentRadius) defined in pdbparser database. In case of xrays or neutrons experimental weights, one can simply set weighting to ‘xrays’ or ‘neutrons’ and the value will be automatically adjusted to respectively ‘atomicNumber’ and ‘neutronCohb’. If attribute values are missing in the pdbparser database, atomic weights must be given in atomsWeight dictionary argument. atomsWeight (None, dict): Atoms weight dictionary where keys are atoms element and values are custom weights. If None is given or partially given, missing elements weighting will be fully set given weighting scheme. scaleFactor (number): A normalization scale factor used to normalize the computed data to the experimental ones. adjustScaleFactor (list, tuple): Used to adjust fit or guess the best scale factor during stochastic engine runtime. It must be a list of exactly three entries. The frequency in number of generated moves of finding the best scale factor. If 0 frequency is given, it means that the scale factor is fixed. The minimum allowed scale factor value. The maximum allowed scale factor value. shapeFuncParams (None, numpy.ndarray, dict): The shape function is subtracted from the total G(r). It must be used when non-periodic boundary conditions are used to take into account the atomic density drop and to correct for the $$\rho_{0}$$ approximation. The shape function can be set to None which means unsused, or set as a constant shape given by a numpy.ndarray or computed from all atoms and updated every ‘updateFreq’ accepted moves. If dict is given the following keywords can be given, otherwise default values will be automatically set. rmin (number) default (0.00) : The minimum distance in $$\AA$$ considered upon building the histogram prior to computing the shape function. If not defined, rmin will be set automatically to 0. rmax (None, number) default (None) : The maximum distance in $$\AA$$ considered upon building the histogram prior to computing the shape function. If not defnined, rmax will be automatically set to $$maximum\ box\ length + 10\AA$$ at engine runtime. dr (number) default (0.5) : The bin size in $$\AA$$ considered upon building the histogram prior to computing the shape function. If not defined, it will be automatically set to 0.5. qmin (number) default (0.001) : The minimum reciprocal distance q in $$\AA^{-1}$$ considered to compute the shape function. If not defined, it will be automatically set to 0.001. qmax (number) default (0.75) : The maximum reciprocal distance q in $$\AA^{-1}$$ considered to compute the shape function. If not defined, it will be automatically set to 0.75. dq (number) default (0.005) : The reciprocal distance bin size in $$\AA^{-1}$$ considered to compute the shape function. If not defined, it will be automatically set to 0.005. updateFreq (integer) default (1000) : The frequency of recomputing the shape function in number of accpeted moves. windowFunction (None, numpy.ndarray): The window function to convolute with the computed pair distribution function of the system prior to comparing it with the experimental data. In general, the experimental pair distribution function G(r) shows artificial wrinkles, among others the main reason is because G(r) is computed by applying a sine Fourier transform to the experimental structure factor S(q). Therefore window function is used to best imitate the numerical artefacts in the experimental data. limits (None, tuple, list): The distance limits to compute the histograms. If None is given, the limits will be automatically set the the min and max distance of the experimental data. Otherwise, a tuple of exactly two items where the first is the minimum distance or None and the second is the maximum distance or None.

NB: If adjustScaleFactor first item (frequency) is 0, the scale factor will remain untouched and the limits minimum and maximum won’t be checked.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.PairDistributionConstraints import PairDistributionConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
PDC = PairDistributionConstraint(experimentalData="pdf.dat", weighting="atomicNumber")

bin

Experimental data distances bin.

minimumDistance

Experimental data minimum distances.

maximumDistance

Experimental data maximum distances.

histogramSize

Histogram size.

experimentalDistances

Experimental distances array.

shellCenters

Shells center array.

shellVolumes

Shells volume array.

experimentalPDF

Experimental pair distribution function data.

elementsPairs

Elements pairs.

weighting

Elements weighting definition.

atomsWeight

Custom atoms weight

weightingScheme

Elements weighting scheme.

windowFunction

Window function.

shapeArray

Shape function data array.

shapeUpdateFreq

Shape function update frequency.

listen(message, argument=None)

Listens to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_shape_function_parameters(shapeFuncParams)

Set the shape function. The shape function can be set to None which means unsused, or set as a constant shape given by a numpy.ndarray or computed from all atoms and updated every ‘updateFreq’ accepted moves. The shape function is subtracted from the total G(r). It must be used when non-periodic boundary conditions are used to take into account the atomic density drop and to correct for the $$\rho_{0}$$ approximation.

Parameters: shapeFuncParams (None, numpy.ndarray, dict): The shape function is subtracted from the total G(r). It must be used when non-periodic boundary conditions are used to take into account the atomic density drop and to correct for the $$\rho_{0}$$ approximation. The shape function can be set to None which means unsused, or set as a constant shape given by a numpy.ndarray or computed from all atoms and updated every ‘updateFreq’ accepted moves. If dict is given the following keywords can be given, otherwise default values will be automatically set. rmin (number) default (0.00) : The minimum distance in $$\AA$$ considered upon building the histogram prior to computing the shape function. If not defined, rmin will be set automatically to 0. rmax (None, number) default (None) : The maximum distance in $$\AA$$ considered upon building the histogram prior to computing the shape function. If not defnined, rmax will be automatically set to $$maximum\ box\ length + 10\AA$$ at engine runtime. dr (number) default (0.5) : The bin size in $$\AA$$ considered upon building the histogram prior to computing the shape function. If not defined, it will be automatically set to 0.5. qmin (number) default (0.001) : The minimum reciprocal distance q in $$\AA^{-1}$$ considered to compute the shape function. If not defined, it will be automatically set to 0.001. qmax (number) default (0.75) : The maximum reciprocal distance q in $$\AA^{-1}$$ considered to compute the shape function. If not defined, it will be automatically set to 0.75. dq (number) default (0.005) : The reciprocal distance bin size in $$\AA^{-1}$$ considered to compute the shape function. If not defined, it will be automatically set to 0.005. updateFreq (integer) default (1000) : The frequency of recomputing the shape function in number of accpeted moves.
set_weighting(weighting)

Set elements weighting. It must be a valid entry of pdbparser atom’s database.

Parameters: weighting (string): The elements weighting scheme. It must be any atomic attribute (atomicNumber, neutronCohb, neutronIncohb, neutronCohXs, neutronIncohXs, atomicWeight, covalentRadius) defined in pdbparser database. In case of xrays or neutrons experimental weights, one can simply set weighting to ‘xrays’ or ‘neutrons’ and the value will be automatically adjusted to respectively ‘atomicNumber’ and ‘neutronCohb’. If attribute values are missing in the pdbparser database, atomic weights must be given in atomsWeight dictionary argument.
set_atoms_weight(atomsWeight)

Custom set atoms weight. This is the way to customize setting atoms weights different than the given weighting scheme.

Parameters: atomsWeight (None, dict): Atoms weight dictionary where keys are atoms element and values are custom weights. If None is given or partially given, missing elements weighting will be fully set given weighting scheme.
set_window_function(windowFunction, frame=None)

Set convolution window function.

Parameters: windowFunction (None, numpy.ndarray): The window function to convolute with the computed pair distribution function of the system prior to comparing it with the experimental data. In general, the experimental pair distribution function G(r) shows artificial wrinkles, among others the main reason is because G(r) is computed by applying a sine Fourier transform to the experimental structure factor S(q). Therefore window function is used to best imitate the numerical artefacts in the experimental data. frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes will be targeted. If subframe is given, all other multiframe subframes will be targeted.
set_experimental_data(experimentalData)

Set constraint’s experimental data.

Parameters: experimentalData (numpy.ndarray, string): The experimental data as numpy.ndarray or string path to load data using numpy.loadtxt function.
set_limits(limits)

Set the histogram computation limits.

Parameters: limits (None, tuple, list): Distance limits to bound experimental data and compute histograms. If None is given, the limits will be automatically set the the min and max distance of the experimental data. Otherwise, a tuple of exactly two items where the first is the minimum distance or None and the second is the maximum distance or None.
check_experimental_data(experimentalData)

Check whether experimental data is correct.

Parameters: experimentalData (object): Experimental data to check. result (boolean): Whether it is correct or not. message (str): Checking message that explains whats’s wrong with the given data.
compute_standard_error(modelData)

Compute the standard error (StdErr) as the squared deviations between model computed data and the experimental ones.

$StdErr = \sum \limits_{i}^{N} W_{i}(Y(X_{i})-F(X_{i}))^{2}$

Where:

$$N$$ is the total number of experimental data points.

$$W_{i}$$ is the data point weight. It becomes equivalent to 1 when dataWeights is set to None.

$$Y(X_{i})$$ is the experimental data point $$X_{i}$$.

$$F(X_{i})$$ is the computed from the model data $$X_{i}$$.

Parameters: modelData (numpy.ndarray): The data to compare with the experimental one and compute the squared deviation. standardError (number): The calculated constraint’s standardError.
update_standard_error()

Compute and set constraint’s standardError.

get_constraint_value(applyMultiframePrior=True)

Compute all partial Pair Distribution Functions (PDFs).

Parameters: applyMultiframePrior (boolean): Whether to apply subframe weight and prior to the total. This will only have an effect when used frame is a subframe and in case subframe weight and prior is defined. PDFs (dictionary): The PDFs dictionnary, where keys are the element wise intra and inter molecular PDFs and values are the computed PDFs.
get_constraint_original_value()

Compute all partial Pair Distribution Functions (PDFs).

Returns: PDFs (dictionary): The PDFs dictionnary, where keys are the element wise intra and inter molecular PDFs and values are the computed PDFs.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint before move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint after move is executed

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if given atom is amputated.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Atom’s relative index as a numpy array of a single element.
accept_amputation(realIndex, relativeIndex)

Accept amputated atom and sets constraints data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
reject_amputation(realIndex, relativeIndex)

Reject amputated atom and set constraint’s data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
get_multiframe_weights(frame)
plot(xlabelParams={'size': 10, 'xlabel': '$r(\\AA)$'}, ylabelParams={'size': 10, 'ylabel': '$G(r)(\\AA^{-2})$'}, **kwargs)

Alias to ExperimentalConstraint.plot with additional parameters

1. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
2. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.

## PairCorrelationConstraints¶

PairCorrelationConstraints contains classes for all constraints related to experimental pair correlation functions.

class fullrmc.Constraints.PairCorrelationConstraints.PairCorrelationConstraint(experimentalData, dataWeights=None, weighting='atomicNumber', atomsWeight=None, scaleFactor=1.0, adjustScaleFactor=(0, 0.8, 1.2), shapeFuncParams=None, windowFunction=None, limits=None)

Controls the total pair correlation function (pcf) of the system noted as g(r). pcf indicates the probability of finding atomic pairs separated by the real space distance r. Theoretically g(r) oscillates about 1. Also $$g(r) \rightarrow 1$$ when $$r \rightarrow \infty$$ and it takes the exact value of zero for $$r$$ shorter than the distance of the closest possible approach of pairs of atoms.

Pair correlation function g(r) and pair distribution function G(r) are directly related as in the following: $$g(r)=1+(\frac{G(r)}{4 \pi \rho_{0} r})$$.

g(r) is calculated after binning all pair atomic distances into a weighted histograms of values $$n(r)$$ from which local number densities are computed as in the following:

$g(r) = \sum \limits_{i,j}^{N} w_{i,j} \frac{\rho_{i,j}(r)}{\rho_{0}} = \sum \limits_{i,j}^{N} w_{i,j} \frac{n_{i,j}(r) / v(r)}{N_{i,j} / V}$

Where:

$$r$$ is the distance between two atoms.

$$\rho_{i,j}(r)$$ is the pair density function of atoms i and j.

$$\rho_{0}$$ is the average number density of the system.

$$w_{i,j}$$ is the relative weighting of atom types i and j.

$$N$$ is the total number of atoms.

$$V$$ is the volume of the system.

$$n_{i,j}(r)$$ is the number of atoms i neighbouring j at a distance r.

$$v(r)$$ is the annulus volume at distance r and of thickness dr.

$$N_{i,j}$$ is the total number of atoms i and j in the system.

Parameters: Refer to PairDistributionConstraint
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.PairCorrelationConstraints import PairCorrelationConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
PCC = PairCorrelationConstraint(experimentalData="pcf.dat", weighting="atomicNumber")

update_standard_error()

Compute and set constraint’s standardError.

get_adjusted_scale_factor(experimentalData, modelData, dataWeights, rho0)

Overload to bring back g(r) to G(r) prior to fitting scale factor. g(r) -> 1 at high r and this will create a wrong scale factor. Overloading can be avoided but it’s better to for performance reasons

get_constraint_value(applyMultiframePrior=True)

Get constraint’s data dictionary value.

Parameters: applyMultiframePrior (boolean): Whether to apply subframe weight and prior to the total. This will only have an effect when used frame is a subframe and in case subframe weight and prior is defined. PDFs (dictionary): The PDFs dictionnary, where keys are the element wise intra and inter molecular PDFs and values are the computed PDFs.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint’s data before move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint’s data after move is executed.

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if given atom is amputated.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Atom’s relative index as a numpy array of a single element.
plot(xlabelParams={'size': 10, 'xlabel': '$r(\\AA)$'}, ylabelParams={'size': 10, 'ylabel': '$g(r)(\\AA^{-2})$'}, **kwargs)

Alias to ExperimentalConstraint.plot with additional parameters

1. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
2. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.

## StructureFactorConstraints¶

StructureFactorConstraints contains classes for all constraints related experimental static structure factor functions.

class fullrmc.Constraints.StructureFactorConstraints.StructureFactorConstraint(experimentalData, dataWeights=None, weighting='atomicNumber', atomsWeight=None, rmin=None, rmax=None, dr=None, scaleFactor=1.0, adjustScaleFactor=(0, 0.8, 1.2), windowFunction=None, limits=None)

Controls the Structure Factor noted as S(Q) and also called total-scattering structure function or Static Structure Factor. S(Q) is a dimensionless quantity and normalized such as the average value $$<S(Q)>=1$$.

It is worth mentioning that S(Q) is nothing other than the normalized and corrected diffraction pattern if all experimental artefacts powder.

The computation of S(Q) is done through an inverse Sine Fourier transform of the computed pair distribution function G(r).

$S(Q) = 1+ \frac{1}{Q} \int_{0}^{\infty} G(r) sin(Qr) dr$

From an atomistic model and histogram point of view, G(r) is computed as the following:

$G(r) = 4 \pi r (\rho_{r} - \rho_{0}) = 4 \pi \rho_{0} r (g(r)-1) = \frac{R(r)}{r} - 4 \pi \rho_{0}$

g(r) is calculated after binning all pair atomic distances into a weighted histograms as the following:

$g(r) = \sum \limits_{i,j}^{N} w_{i,j} \frac{\rho_{i,j}(r)}{\rho_{0}} = \sum \limits_{i,j}^{N} w_{i,j} \frac{n_{i,j}(r) / v(r)}{N_{i,j} / V}$

Where:

$$Q$$ is the momentum transfer.

$$r$$ is the distance between two atoms.

$$\rho_{i,j}(r)$$ is the pair density function of atoms i and j.

$$\rho_{0}$$ is the average number density of the system.

$$w_{i,j}$$ is the relative weighting of atom types i and j.

$$R(r)$$ is the radial distribution function (rdf).

$$N$$ is the total number of atoms.

$$V$$ is the volume of the system.

$$n_{i,j}(r)$$ is the number of atoms i neighbouring j at a distance r.

$$v(r)$$ is the annulus volume at distance r and of thickness dr.

$$N_{i,j}$$ is the total number of atoms i and j in the system.

 Reduced structure factor of memory shape Nickel-Titanium alloy.
Parameters: experimentalData (numpy.ndarray, string): Experimental data as numpy.ndarray or string path to load data using numpy.loadtxt method. dataWeights (None, numpy.ndarray): Weights array of the same number of points of experimentalData used in the constraint’s standard error computation. Therefore particular fitting emphasis can be put on different data points that might be considered as more or less important in order to get a reasonable and plausible modal. If None is given, all data points are considered of the same importance in the computation of the constraint’s standard error. If numpy.ndarray is given, all weights must be positive and all zeros weighted data points won’t contribute to the total constraint’s standard error. At least a single weight point is required to be non-zeros and the weights array will be automatically scaled upon setting such as the the sum of all the weights is equal to the number of data points. weighting (string): The elements weighting scheme. It must be any atomic attribute (atomicNumber, neutronCohb, neutronIncohb, neutronCohXs, neutronIncohXs, atomicWeight, covalentRadius) defined in pdbparser database. In case of xrays or neutrons experimental weights, one can simply set weighting to ‘xrays’ or ‘neutrons’ and the value will be automatically adjusted to respectively ‘atomicNumber’ and ‘neutronCohb’. If attribute values are missing in the pdbparser database, atomic weights must be given in atomsWeight dictionary argument. atomsWeight (None, dict): Atoms weight dictionary where keys are atoms element and values are custom weights. If None is given or partially given, missing elements weighting will be fully set given weighting scheme. rmin (None, number): The minimum distance value to compute G(r) histogram. If None is given, rmin is computed as $$2 \pi / Q_{max}$$. rmax (None, number): The maximum distance value to compute G(r) histogram. If None is given, rmax is computed as $$2 \pi / dQ$$. dr (None, number): The distance bin value to compute G(r) histogram. If None is given, bin is computed as $$2 \pi / (Q_{max}-Q_{min})$$. scaleFactor (number): A normalization scale factor used to normalize the computed data to the experimental ones. adjustScaleFactor (list, tuple): Used to adjust fit or guess the best scale factor during stochastic engine runtime. It must be a list of exactly three entries. The frequency in number of generated moves of finding the best scale factor. If 0 frequency is given, it means that the scale factor is fixed. The minimum allowed scale factor value. The maximum allowed scale factor value. windowFunction (None, numpy.ndarray): The window function to convolute with the computed pair distribution function of the system prior to comparing it with the experimental data. In general, the experimental pair distribution function G(r) shows artificial wrinkles, among others the main reason is because G(r) is computed by applying a sine Fourier transform to the experimental structure factor S(q). Therefore window function is used to best imitate the numerical artefacts in the experimental data. limits (None, tuple, list): The distance limits to compute the histograms. If None is given, the limits will be automatically set the the min and max distance of the experimental data. Otherwise, a tuple of exactly two items where the first is the minimum distance or None and the second is the maximum distance or None.

NB: If adjustScaleFactor first item (frequency) is 0, the scale factor will remain untouched and the limits minimum and maximum won’t be checked.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Constraints.StructureFactorConstraints import StructureFactorConstraint

# create engine
ENGINE = Engine(path='my_engine.rmc')

# set pdb file
ENGINE.set_pdb('system.pdb')

# create and add constraint
SFC = StructureFactorConstraint(experimentalData="sq.dat", weighting="atomicNumber")

rmin

Histogram minimum distance.

rmax

Histogram maximum distance.

dr

Histogram bin size.

bin

Computed histogram distance bin size.

minimumDistance

Computed histogram minimum distance.

maximumDistance

Computed histogram maximum distance.

qmin

Experimental data reciprocal distances minimum.

qmax

Experimental data reciprocal distances maximum.

dq

Experimental data reciprocal distances bin size.

experimentalQValues

Experimental data used q values.

histogramSize

Histogram size

shellCenters

Shells center array

shellVolumes

Shells volume array

experimentalSF

Experimental Structure Factor or S(q)

elementsPairs

Elements pairs

atomsWeight

Custom atoms weight

weighting

Elements weighting definition.

weightingScheme

Elements weighting scheme.

windowFunction

Convolution window function.

Gr2SqMatrix

G(r) to S(q) transformation matrix.

listen(message, argument=None)

Listens to any message sent from the Broadcaster.

Parameters: message (object): Any python object to send to constraint’s listen method. argument (object): Any type of argument to pass to the listeners.
set_rmin(rmin)

Set rmin value.

Parameters: rmin (None, number): The minimum distance value to compute G(r) histogram. If None is given, rmin is computed as $$2 \pi / Q_{max}$$.
set_rmax(rmax)

Set rmax value.

Parameters: rmax (None, number): The maximum distance value to compute G(r) histogram. If None is given, rmax is computed as $$2 \pi / dQ$$.
set_dr(dr)

Set dr value.

Parameters: dr (None, number): The distance bin value to compute G(r) histogram. If None is given, bin is computed as $$2 \pi / (Q_{max}-Q_{min})$$.
set_weighting(weighting)

Set elements weighting. It must be a valid entry of pdbparser atom’s database.

Parameters: weighting (string): The elements weighting scheme. It must be any atomic attribute (atomicNumber, neutronCohb, neutronIncohb, neutronCohXs, neutronIncohXs, atomicWeight, covalentRadius) defined in pdbparser database. In case of xrays or neutrons experimental weights, one can simply set weighting to ‘xrays’ or ‘neutrons’ and the value will be automatically adjusted to respectively ‘atomicNumber’ and ‘neutronCohb’. If attribute values are missing in the pdbparser database, atomic weights must be given in atomsWeight dictionary argument.
set_atoms_weight(atomsWeight)

Custom set atoms weight. This is the way to setting a atoms weights different than the given weighting scheme.

Parameters: atomsWeight (None, dict): Atoms weight dictionary where keys are atoms element and values are custom weights. If None is given or partially given, missing elements weighting will be fully set given weighting scheme.
set_window_function(windowFunction)

Set convolution window function.

Parameters: windowFunction (None, numpy.ndarray): The window function to convolute with the computed pair distribution function of the system prior to comparing it with the experimental data. In general, the experimental pair distribution function G(r) shows artificial wrinkles, among others the main reason is because G(r) is computed by applying a sine Fourier transform to the experimental structure factor S(q). Therefore window function is used to best imitate the numerical artefacts in the experimental data.
set_experimental_data(experimentalData)

Set constraint’s experimental data.

Parameters: experimentalData (numpy.ndarray, string): The experimental data as numpy.ndarray or string path to load data using numpy.loadtxt function.
set_limits(limits)

Set the reciprocal distance limits (qmin, qmax).

Parameters: limits (None, tuple, list): Distance limits to bound experimental data and compute histograms. If None is given, the limits will be automatically set to min and max reciprocal distance recorded in experimental data. If given, a tuple of minimum reciprocal distance (qmin) or None and maximum reciprocal distance (qmax) or None should be given.
update_standard_error()

Compute and set constraint’s standardError.

check_experimental_data(experimentalData)

Check whether experimental data is correct.

Parameters: experimentalData (object): The experimental data to check. result (boolean): Whether it is correct or not. message (str): Checking message that explains whats’s wrong with the given data
compute_standard_error(modelData)

Compute the standard error (StdErr) as the squared deviations between model computed data and the experimental ones.

$StdErr = \sum \limits_{i}^{N} W_{i}(Y(X_{i})-F(X_{i}))^{2}$

Where:

$$N$$ is the total number of experimental data points.

$$W_{i}$$ is the data point weight. It becomes equivalent to 1 when dataWeights is set to None.

$$Y(X_{i})$$ is the experimental data point $$X_{i}$$.

$$F(X_{i})$$ is the computed from the model data $$X_{i}$$.

Parameters: modelData (numpy.ndarray): The data to compare with the experimental one and compute the squared deviation. standardError (number): The calculated constraint’s standardError.
get_adjusted_scale_factor(experimentalData, modelData, dataWeights)

Overload to reduce S(q) prior to fitting scale factor. S(q) -> 1 at high q and this will create a wrong scale factor. Overloading can be avoided but it’s better to for performance reasons

get_constraint_value(applyMultiframePrior=True)

Compute all partial Structure Factor (SQs).

Parameters: applyMultiframePrior (boolean): Whether to apply subframe weight and prior to the total. This will only have an effect when used frame is a subframe and in case subframe weight and prior is defined. SQs (dictionary): The SQs dictionnary, where keys are the element wise intra and inter molecular SQs and values are the computed SQs.
get_constraint_original_value()

Compute all partial Pair Distribution Functions (PDFs).

Returns: PDFs (dictionary): The PDFs dictionnary, where keys are the element wise intra and inter molecular PDFs and values are the computed PDFs.
compute_data(*args, **kwargs)

Compute constraint’s data.

Parameters: update (boolean): whether to update constraint data and standard error with new computation. If data is computed and updated by another thread or process while the stochastic engine is running, this might lead to a state alteration of the constraint which will lead to a no additional accepted moves in the run data (dict): constraint data dictionary standardError (float): constraint standard error
compute_before_move(realIndexes, relativeIndexes)

Compute constraint before move is executed

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to.
compute_after_move(realIndexes, relativeIndexes, movedBoxCoordinates)

Compute constraint after move is executed

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Group atoms relative index the move will be applied to. movedBoxCoordinates (numpy.ndarray): The moved atoms new coordinates.
accept_move(realIndexes, relativeIndexes)

Accept move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
reject_move(realIndexes, relativeIndexes)

Reject move

Parameters: realIndexes (numpy.ndarray): Not used here. relativeIndexes (numpy.ndarray): Not used here.
compute_as_if_amputated(realIndex, relativeIndex)

Compute and return constraint’s data and standard error as if given atom is amputated.

Parameters: realIndex (numpy.ndarray): Atom’s index as a numpy array of a single element. relativeIndex (numpy.ndarray): Atom’s relative index as a numpy array of a single element.
accept_amputation(realIndex, relativeIndex)

Accept amputated atom and sets constraints data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
reject_amputation(realIndex, relativeIndex)

Reject amputated atom and set constraint’s data and standard error accordingly.

Parameters: realIndex (numpy.ndarray): Not used here. relativeIndex (numpy.ndarray): Not used here.
plot(xlabelParams={'size': 10, 'xlabel': '$Q(\\AA^{-1})$'}, ylabelParams={'size': 10, 'ylabel': '$S(Q)$'}, **kwargs)

Alias to ExperimentalConstraint.plot with additional parameters

1. xlabelParams (None, dict): modified matplotlib.axes.Axes.set_xlabel parameters.
2. ylabelParams (None, dict): modified matplotlib.axes.Axes.set_ylabel parameters.
class fullrmc.Constraints.StructureFactorConstraints.ReducedStructureFactorConstraint(experimentalData, dataWeights=None, weighting='atomicNumber', atomsWeight=None, rmin=None, rmax=None, dr=None, scaleFactor=1.0, adjustScaleFactor=(0, 0.8, 1.2), windowFunction=None, limits=None)

The Reduced Structure Factor that we will also note S(Q) is exactly the same quantity as the Structure Factor but with the slight difference that it is normalized to 0 rather than 1 and therefore $$<S(Q)>=0$$.

The computation of S(Q) is done through a Sine inverse Fourier transform of the computed pair distribution function noted as G(r).

$S(Q) = \frac{1}{Q} \int_{0}^{\infty} G(r) sin(Qr) dr$

The only reason why the Reduced Structure Factor is implemented, is because many experimental data are treated in this form. And it is just convenient not to manipulate the experimental data every time.

get_adjusted_scale_factor(experimentalData, modelData, dataWeights)

dummy overload that does exactly the same thing

plot(xlabelParams={'size': 10, 'xlabel': '$Q(\\AA^{-1})$'}, ylabelParams={'size': 10, 'ylabel': '$S(Q)-1$'}, **kwargs)

Alias to ExperimentalConstraint.plot with additional parameters