GroupSelector contains parent classes for all group selectors. A GroupSelector is used at the stochastic engine’s runtime to select groups upon which a move will be applied. Therefore it has become possible to fully customize the selection of groups of atoms and to choose when and how frequently a group can be chosen to perform a move upon.
fullrmc.Core.GroupSelector.GroupSelector(engine=None)Bases: object
Group selector is the parent class that selects groups to perform moves at stochastic engine’s runtime.
| Parameters: |
|
|---|
engineStochastic engine’s instance.
refineGet refine flag value. It will always return False because refine is a property of RecursiveGroupSelector instances only.
exploreGet explore flag value. It will always return False because explore is a property of RecursiveGroupSelector instances only.
willSelectGet whether next step a new selection is occur or still the same group is going to be selected again. It will always return True because recurrence is a property of RecursiveGroupSelector instances only.
willRecurGet whether next step the same group will be returned. It will always return False because this is a property of RecursiveGroupSelector instances only.
willRefineGet whether selection is recurring and refine flag is True. It will always return False because recurrence is a property of RecursiveGroupSelector instances only.
willExploreGet whether selection is recurring and explore flag is True. It will always return False because recurrence is a property of RecursiveGroupSelector instances only.
isNewSelectionGet whether the last step a new selection was made. It will always return True because recurrence is a property of RecursiveGroupSelector instances only.
isRecurringGet whether the last step the same group was returned. It will always return False because this is a property of RecursiveGroupSelector instances only.
isRefiningGet whether selection is recurring and refine flag is True. It will always return False because recurrence is a property of RecursiveGroupSelector instances only.
isExploringGet whether selection is recurring and explore flag is True. It will always return False because recurrence is a property of RecursiveGroupSelector instances only.
set_engine(engine)Set selector’s stochastic engine instance.
| Parameters: |
|
|---|
select_index()This method must be overloaded in every GroupSelector sub-class
| Returns: |
|
|---|
move_accepted(index)This method is called by the stochastic engine when a move generated on a group is accepted. This method is empty must be overloaded when needed.
| Parameters: |
|
|---|
move_rejected(index)This method is called by the stochastic engine when a move generated on a group is rejected. This method is empty must be overloaded when needed.
| Parameters: |
|
|---|
fullrmc.Core.GroupSelector.RecursiveGroupSelector(selector, recur=10, override=True, refine=False, explore=False)Bases: fullrmc.Core.GroupSelector.GroupSelector
Recursive selector is the only selector that can use the recursive property on a selection. It is used as a wrapper around a GroupSelector instance.
| Parameters: |
|
|---|
NB: refine and explore flags can’t both be set to True at the same time. When this happens refine flag gets automatically switched to False. The usage of those flags is very important because they allow groups of atoms to go out of local minima in the energy surface. The way traditional reverse mote carlo works is by minimizing the total energy of the system (error) using gradient descent method. Using of those flags allows the system to go up hill in the energy surface searching for other lower minimas, while always conserving the lowest energy state found and not changing the system structure until a better structure with smaller error is found.
The following video compares the Reverse Monte Carlo traditional fitting mode with fullrmc's recursive selection one with explore flag set to True. From a potential point of view, exploring allows to cross forbidden unlikely energy barriers and going out of local minimas.
The following video is an example of refining the position of a molecule using RecursiveGroupSelector and setting refine flag to True. The molecule is always refined from its original position towards a new one generated by the move generator.
The following video is an example of exploring the space of a molecule using RecursiveGroupSelector and setting explore flag to True. The molecule explores the allowed space by wandering via its move generator and only moves enhancing the structure are stored.
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Core.GroupSelector import RecursiveGroupSelector
# create engine
ENGINE = Engine(path='my_engine.rmc')
# set pdb file
ENGINE.set_pdb('system.pdb')
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...
##### Wrap engine group selector with a recursive group selector. #####
# create recursive group selector. Recurrence is set to 20 with explore flag set to True.
RGS = RecursiveGroupSelector(ENGINE.groupSelector, recur=20, refine=False, explore=True)
ENGINE.set_group_selector(RGS)
selectorThe wrapped selector instance.
lastSelectedIndexThe last selected group index.
willSelectGet whether next step a new selection is occur or still the same group is going to be selected again.
willRecurGet whether next step the same group will be returned.
willRefineGet whether next step the same group will be returned and refine flag is True.
willExploreGet whether next step the same group will be returned and explore flag is True.
isNewSelectionGet whether this last step a new selection was made.
isRecurringGet whether this last step the same group was returned.
isRefiningGet whether this last step the same group was returned and refine flag is True.
isExploringGet whether this last step the same group was returned and explore flag is True.
overrideOverride flag value.
refineRefine flag value.
exploreExplore flag value.
currentRecurThe current recur value which is selected group dependant when override flag is True.
recurThe current recur value. The set recur value can change during engine runtime if override flag is True. To get the recur value as set by set_recur method recurAsSet must be used.
recurAsSetGet recur value as set but set_recur method.
positionGet the position of the selector in the path.
engineGet the wrapped selector engine instance.
set_engine(engine)Sets the wrapped selector stochastic engine instance.
| Parameters: |
|
|---|
set_recur(recur)Sets the recur value.
| Parameters: |
|
|---|
set_override(override)Select override value.
| Parameters: |
|
|---|
set_refine(refine)Select override value.
| Parameters: |
|
|---|
set_explore(explore)Select override value.
| Parameters: |
|
|---|
select_index()Select new index.
| Returns: |
|
|---|
OrderedSelectors contains GroupSelector classes of defined order of selection.
fullrmc.Selectors.OrderedSelectors.DefinedOrderSelector(engine, order=None)¶Bases: fullrmc.Core.GroupSelector.GroupSelector
DefinedOrderSelector is a group selector with a defined order of selection.
| Parameters: |
|
|---|
# import external libraries
import numpy as np
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Selectors.OrderedSelectors import DefinedOrderSelector
# create engine
ENGINE = Engine(path='my_engine.rmc')
# set pdb file
ENGINE.set_pdb('system.pdb')
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups generators as needed ...
##### set the order of selection from closest to the origin to the further. #####
# compute groups centers
centers = [np.sum(ENGINE.realCoordinates[g.indexes], axis=0)/len(g) for g in ENGINE.groups]
# compute distances to origin
distances = [np.sqrt(np.add.reduce(c**2)) for c in centers]
# compute increasing order
order = np.argsort(distances)
# set group selector
ENGINE.set_group_selector( DefinedOrderSelector(engine=ENGINE, order=order) )
order¶List copy of the order of selection.
index¶The current selection index.
set_order(order)¶Set selector groups order.
| Parameters: |
|
|---|
select_index()¶Select index.
| Returns: |
|
|---|
fullrmc.Selectors.OrderedSelectors.DirectionalOrderSelector(engine, center=None, expand=True, adjustMoveGenerators=False, generatorsParams={'RG': {'amplitude': 10}, 'TG': {'amplitude': 0.1, 'angle': 90, 'damping': 0.1}})¶Bases: fullrmc.Selectors.OrderedSelectors.DefinedOrderSelector
DirectionalOrderSelector is a group selector with a defined order of selection. The order of selection is computed automatically at engine runtime by computing Groups distance to center, and setting the order from the further to the closest if expand argument is True or from the closest to the further if expand is False.
| Parameters: |
|
|---|
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Selectors.OrderedSelectors import DirectionalOrderSelector
# create engine
ENGINE = Engine(path='my_engine.rmc')
# set pdb file
ENGINE.set_pdb('system.pdb')
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups generators as needed ...
# Set the order of selection from further to the closest to a (1,1,1).
# Automatically adjust the groups move generators allowing modulation of amplitudes.
ENGINE.set_group_selector( DirectionalOrderSelector(engine = ENGINE,
center = (1,1,1),
adjustMoveGenerators = True) )
expand¶expand flag.
center¶center (X,Y,Z) coordinates.
adjustMoveGenerators¶adjustMoveGenerators flag.
generatorsParams¶Automatic generators parameters.
set_generators_parameters(generatorsParams)¶Set move generators parameters.
generatorsParams (None, dict): The automatically created moves generators parameters. If None is given, default parameters are used. If a dictionary is given, only two keys are allowed. ‘TG’ key is for TranslationTowardsCenterGenerator parameters and ‘RG’ key is for RotationGenerator parameters. TranslationTowardsCenterGenerator amplitude parameter is not the same for all groups but intelligently allowing certain groups to move more than others according to damping parameter.
Parameters are the following:
Parameters are used as the following:
TG = TranslationTowardsCenterGenerator(center={“fixed”:center}, amplitude=AMPLITUDE, angle=TG_ang)
Where TG_amp < AMPLITUDE < TG_amp.TG_dam
RG = RotationGenerator(amplitude=RG_ang)
MoveGeneratorCollector(collection=[TG,RG], randomize=True)
NB: The parameters are not checked for errors until engine runtime.
set_center(center)¶Set the center.
| Parameters: |
|
|---|
set_expand(expand)¶Set expand.
| Parameters: |
|
|---|
set_adjust_move_generators(adjustMoveGenerators)¶Set expand.
| Parameters: |
|
|---|
RandomSelectors contains GroupSelector classes of random order of selections.
Machine learning on group selection is shown herein. Groups are set to single atom where only random
translation moves generators with different amplitudes are used allowing moves to be accepted in different
ratios. In those two examples SmartRandomSelector allowing machine learning upon group
selection. No experimental constraints are used but only inter-molecular distances, intra-molecular bonds,
angles and improper angles constraints are used to keep the integrity of the system and molecules.
As one can see, group selection machine learning is very effective allowing consequent improvement on the
accepted moves. Still, fast convergence of the system and the ratio of accepted moves is highly correlated
with the move generator assigned to the groups. |
|
25% of assigned moves generators amplitude is set to 10A allowing very few moves on those groups to be accepted and the rest of moves generators amplitudes is set to 0.3A. |
25% of assigned moves generators amplitude is set to 10A allowing very few moves on those groups to be accepted and the rest of moves generators amplitudes is set to 0.25A. |
fullrmc.Selectors.RandomSelectors.RandomSelector(engine=None)¶Bases: fullrmc.Core.GroupSelector.GroupSelector
RandomSelector generates indexes randomly for engine group selection.
| Parameters: |
|
|---|
# import external libraries
import numpy as np
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Selectors.RandomSelectors import RandomSelector
# create engine
ENGINE = Engine(path='my_engine.rmc')
# set pdb file
ENGINE.set_pdb('system.pdb')
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups generators as needed ...
# set group selector as random selection from all defined groups.
ENGINE.set_group_selector( RandomSelector(engine=ENGINE) )
select_index()¶Select index.
| Returns: |
|
|---|
fullrmc.Selectors.RandomSelectors.WeightedRandomSelector(engine, weights=None)¶Bases: fullrmc.Selectors.RandomSelectors.RandomSelector
WeightedRandomSelector generates indexes randomly following groups weighting scheme.
| Parameters: |
|
|---|
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Selectors.RandomSelectors import WeightedRandomSelector
# create engine
ENGINE = Engine(path='my_engine.rmc')
# set pdb file
ENGINE.set_pdb('system.pdb')
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups generators as needed ...
# set group selector as random selection but with double likelihood to
# selecting the first and the last group.
WEIGHTS = [[idx,1] for idx in range(len(ENGINE.groups))]
WEIGHTS[0][1] = WEIGHTS[-1][1] = 2
ENGINE.set_group_selector( WeightedRandomSelector(engine=ENGINE, weights=WEIGHTS) )
weights¶Groups weight of selection as initialized.
groupsWeight¶Groups weight of selection at current state.
selectionScheme¶Groups selection scheme used upon group selection.
set_weights(weights)¶Set groups selection weighting scheme.
| Parameters: |
|
|---|
set_group_weight(groupWeight)¶Set a single group weight.
| Parameters: |
|
|---|
select_index()¶Select index.
| Returns: |
|
|---|
fullrmc.Selectors.RandomSelectors.SmartRandomSelector(engine, weights=None, biasFactor=1, unbiasFactor=None)¶Bases: fullrmc.Selectors.RandomSelectors.WeightedRandomSelector
SmartRandomSelector is a random group selector fed with machine learning algorithm. The indexes generation is biased and it evolves throughout the simulation towards selecting groups with more successful moves history.
| Parameters: |
|
|---|
# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Selectors.RandomSelectors import SmartRandomSelector
# create engine
ENGINE = Engine(path='my_engine.rmc')
# set pdb file
ENGINE.set_pdb('system.pdb')
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups generators as needed ...
# set group selector as random smart selection that will adjust its
# weighting scheme to improve the chances of moves getting accepted.
ENGINE.set_group_selector( SmartRandomSelector(engine=ENGINE) )
biasFactor¶The biasing factor.
unbiasFactor¶The unbiasing factor.
set_bias_factor(biasFactor)¶Set the biasing factor.
| Parameters: |
|
|---|
set_unbias_factor(unbiasFactor)¶Set the unbiasing factor.
| Parameters: |
|
|---|
move_accepted(index)¶This method is called by the engine when a move generated on a group is accepted. This method is empty must be overloaded when needed.
| Parameters: |
|
|---|
move_rejected(index)¶This method is called by the engine when a move generated on a group is rejected. This method is empty must be overloaded when needed.
| Parameters: |
|
|---|
select_index()¶Select index.
| Returns: |
|
|---|
fullrmc.Selectors.RandomSelectors.generate_random_float()¶random() -> x in the interval [0, 1).