MoveGenerator contains parent classes for all move generators. A MoveGenerator sub-class is used at fullrmc’s stochastic engine runtime to generate moves upon selected groups. Every group has its own MoveGenerator class and definitions, therefore it is possible to fully customize how a group of atoms should move.

Inheritance diagram of fullrmc.Core.MoveGenerator

fullrmc.Core.MoveGenerator.generate_random_float(): random() -> x in the interval [0, 1).

class fullrmc.Core.MoveGenerator.MoveGenerator(group=None, *args, **kwargs)

Bases: object

It is the parent class of all moves generators. This class can’t be instantiated but its sub-classes might be.

Parameters:

group (None, Group): The group instance.

classmethod create(params, *args, **kwargs)

Create a move generator instance given instantiation parameters

Parameters:

params (dict): instantiation parameters

Returns:

obj (MoveGenerator): the created instance

parameters(*args, **kwargs): Design pattern implementation.

update(params)

Design pattern implementation, must be overloaded by all MoveGenerator sub-classes that need a way to update their state.

Parameters:

params (dict): The update parameters, sub-class specific.

property group

Group instance.

Returns:

group (None, Group): The group instance this generator is attached to.

set_group(group)

Set the MoveGenerator group.

Parameters:

group (None, Group): Group instance.

check_group(group)

Check the generator’s group. This method must be overloaded in all MoveGenerator sub-classes.

Parameters:

group (Group): the Group instance

transform_coordinates(coordinates, argument=None)

Transform coordinates. This method is called to move atoms. This method must be overloaded in all MoveGenerator sub-classes.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the move.
argument (object): Any other argument needed to perform the move. In General it’s not needed.

Returns:

coordinates (np.ndarray): The new coordinates after applying the move.

move(coordinates, _resetRuntimeData=True)

Moves coordinates. This method must NOT be overloaded in MoveGenerator sub-classes.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the transformation.
_resetRuntimeData (bool): Internal fullrmc engine flag. When True (default), the generator’s runtimeData dictionary is cleared before applying the move. End users should not need to alter this.

Returns:

coordinates (np.ndarray): The new coordinates after applying the transformation.

class fullrmc.Core.MoveGenerator.RequireMoveGeneratorMeta(name, bases, dct)

Bases: type

Metaclass enforcing that every class using it (except the internal AxisUtils and AmplitudeUtils mixin base classes) must also inherit from MoveGenerator. This prevents accidentally building a utils mixin class that isn’t a proper move generator.

class fullrmc.Core.MoveGenerator.PositionUtils(*args, **kwargs)

Bases: object

Utils class managing position setting and runtime calculations.

class fullrmc.Core.MoveGenerator.AmplitudeUtils(*args, **kwargs)

Bases: object

Mixin class adding amplitude bounds checking and amplitude get/set behavior to MoveGenerator sub-classes that move atoms by a bounded random amplitude (e.g. translations, rotations amplitude).

property amplitude

Amplitude value.

Returns:

amplitude (tuple): The (min, max) amplitude tuple currently set, defaulting to (0., 0.1) if never explicitly set.

property amplitude_utils_parameters

Get current state and instantiation parameters.

Returns:

parameters (dict): A dictionary holding the current amplitude value under the ‘amplitude’ key.

set_amplitude(amplitude)

Set amplitude.

Parameters:

amplitude (number, tuple): The amplitude value.. If number is given, it is the maximum or minimum amplitude. If tuple of length 2 is given, it is the limits given in (min, max) If tuple of length 3 is given, it must be the limits in X, Y and Z directions given as numbers or tuples of length 2

class fullrmc.Core.MoveGenerator.AxisUtils(*args, **kwargs)

Bases: PositionUtils

Mixin class adding axis, direction and randomization-angle get/set behavior to MoveGenerator sub-classes that move atoms along or around an axis (e.g. rotations, translations along an axis).

property axis

Axis value or definition.

Returns:

axis (None, object): The current axis definition, or None if never explicitly set.

property direction

Direction value.

Returns:

direction (str): The current direction value, defaulting to ‘any’ if never explicitly set.

property angle

Solid angle value to randomize axis during runtime.

Returns:

angle (None, float): The solid angle in radians, or None if never explicitly set.

property axis_utils_parameters

Get current state and instantiation parameters.

Returns:

parameters (dict): A dictionary holding the current direction, axis and angle (converted to degrees) values.

set_axis(axis)

Set the axis along which the translation will be performed.

Parameters:

axis (None, integer,set,list,tuple,numpy.ndarray,dict): Translation axis vector. If integer, it must be 0,1 or 2 indicating the symmetry axis of translation which will be computed everytime at engine runtime If set, it will contain the atoms indexes to compute a center and then translation axis will be pointing from the coordinates center to the listed atoms center If list,tuple,numpy.ndarray it must be of length three which is a fixed axis If a dict is given, then it must contain a type and a value. type can be ‘symmetry_axis’ similar to integer, ‘to_position’ similar to set or ‘fixed_axis’ similar to list. ‘from_to’ is another axis type, where the value is a dict containing two keys ‘from’ and ‘to’ and the values of those are a dictionary containing a single key of value ‘atoms’, ‘generator_group’ or ‘moved_coordinates’ and the value must be a list of indexes. Another key can be given ‘fixed’, the value must be a a list of three numbers. ‘plane’ is another axis type, where the value is a dict containing ‘p0’, ‘p1’, ‘p2’ coordinates or atom indexes and a possible ‘normal’ flag to generate axis perpendicular to the plane. ‘circle’ is another axis type, where axis will be along the tangent to a circle at point. The value is a dict containing ‘center’, ‘point’, ‘planePoint’.

TG = Translations.TranslationGenerator()
# fixed_axis
# values are a vector in 3d
TG.set_axis({ 'type':'fixed_axis', 'value':[0,0,1] })
# symmetry_axis
#. values can be 0,1,2 or any of 'atoms', 'generator_group', 'engine_group', 'moved_coordinates'
TG.set_axis({'type':'symmetry_axis', 'value':0})
TG.set_axis({'type':'symmetry_axis', 'value':{'engine_group': {'group_index':0,
                                                             'atoms':[0,3,4]}
                                                             }
                                        }
         )
# to_position
# value can be any position
TG.set_axis({'type': 'to_position', 'value': {'fixed': [0, 5.3, 10]}})
TG.set_axis({'type': 'to_position', 'value': {'atoms': [0,3,6,4]}})
TG.set_axis({'type': 'to_position', 'value': {'generator_group': None}})
TG.set_axis({'type': 'to_position', 'value': {'moved_coordinates': None}})
TG.set_axis({'type': 'to_position', 'value': {'moved_coordinates': [0, 1, 4]}})
TG.set_axis({'type': 'to_position', 'value': {'engine_group': {'group_index': 0, 'atoms': [0, 1, 2]}}})
# from_to
# value is a dictionary with 'from' position and 'to' position
TG.set_axis({ 'type':'from_to', 'value':{'from': {'fixed': [0,5.3, 10]},
                                         'to'  : {'atoms': [10,11,14,15]}
                                        }
            })
TG.set_axis({ 'type':'from_to', 'value':{'from': {'engine_group': {'group_index':0,}},
                                         'to'  : {'atoms': [0,1,2]}
                                        }
            })
# plane
# value is a dictionary with 'p0', 'p1','p2' and optional 'normal' key
TG.set_axis({'type': 'plane', 'value': {'p0':{'fixed': [0,0,0]},
                                        'p1':{'atoms': [0,3,6,4]},
                                        'p2':{'engine_group': {'group_index': 0, 'atoms': [0, 1, 2]},
                                        'normal': False}}
           })
# circle
# value is a dictionary with 'center', 'point' and 'planePoint' key
TG.set_axis({'type': 'circle', 'value': {'center':{'fixed': [0,0,0]},
                                         'point':{'atoms': [0,3,6,4]},
                                         'planePoint':{'moved_coordinates': None},
                                        }
           })

set_angle(angle)

Set the tolerance maximum angle.

Parameters:

angle (None, number): The maximum tolerance angle in degrees between a generated translation vector and the pre-defined axis.

set_direction(direction)

Sets the generated translation vectors direction.

Parameters:

direction (‘same’, ‘opposite’, ‘any’, dict): Whether to generate translation vector in the same direction of axis or not. If ‘same’ all generated vectors are in the same direction of axis. If ‘opposite’ all generated vectors are in the opposite direction of axis. If ‘any’ generated axis can be in the same direction of axis or in t he opposite. If dict is given, keys can be ‘same’, ‘opposite’, ‘any’, ‘set 1’ and ‘set 2’. the values must be lists of atoms in the group indexes ranging from 0 to the number of atoms in the group. atoms in ‘same’ will be translated in the same direction as the vector, ‘opposite’ in the opposite direction and ‘any’ will be all translated in any of the directions same or opposite. atoms listed in ‘set 1’ and ‘set 2’ will be randomly translated in different directions e.g. if ‘set 1’ are translated in the same direction, ‘set 2’ will be translated in the opposite direction and vice-versa

class fullrmc.Core.MoveGenerator.RemoveGenerator(group=None, maximumCollected=None, allowFittingScaleFactor=False, atomsList=None)

Bases: MoveGenerator

This is a very particular move generator that will not generate moves on atoms but removes them from the atomic configuration using a general collector mechanism. Remove generators must be used to create defects in the simulated system. When the standard error is high, removing atoms might reduce the total fit standard error but this can be illusional and very limiting because artificial non physical voids can get created in the system which will lead to an impossibility to finding a solution at the end. It’s strongly recommended to exhaust all ideas and possibilities in finding a good solution prior to start removing atoms unless structural defects is the goal of the simulation.

All removed or amputated atoms are collected by the engine and will become available to be re-inserted in the system if needed. But keep in mind, it might be physically easy to remove and atom but an impossibility to add it back especially if the created voids are smeared out.

Removers are called generators but they behave like selectors. Instead of applying a certain move on a group of atoms, they normally pick atoms from defined atoms list and apply no moves on those. ‘move’ and ‘transform_coordinates’ methods are not implemented in this class of generators and a usage error will be raised if called. ‘pick_from_list’ method is used instead and must be overloaded by all RemoveGenerator subclasses.

N.B. This class can’t be instantiated but its sub-classes might be.

Parameters:

group (None, Group): The group instance which is this case must be fullrmc EmptyGroup.
maximumCollected (None, Integer): The maximum number allowed of atoms to be removed and collected from atomic configuration by the stochastic engine. This property is general to the system and checks engine’s collected atoms not the number of removed atoms via this generator. If None is given, the remover will not check for the number of already removed atoms before attempting a remove.
allowFittingScaleFactor (bool): Constraints and especially experimental ones have a scale factor constant that can be fit. Fitting a scale factor happens at stochastic engine’s runtime at a certain fitting frequency. If this flag set to True, then fitting the scale factor will be allowed upon removing atoms. When set to False, fitting the constraint scale factor will be forbidden upon removing atoms. By default, allowFittingScaleFactor is set to False because it’s more logical to allow removing only atoms that enhances the total standard error without rescaling the model’s data.
atomsList (None,list,set,tuple,np.ndarray): The list of atomss index to chose and remove from.

property atomsList

Atoms list from which atoms will be picked to attempt removal.

Returns:

atomsList (None, np.ndarray): The atoms indexes list.

property allowFittingScaleFactor

Whether to allow constraints to fit their scale factor upon removing atoms.

Returns:

allowFittingScaleFactor (bool): The allow fitting scale factor flag value.

property maximumCollected

Maximum collected atoms allowed.

Returns:

maximumCollected (None, integer): The maximum number of already-collected atoms allowed.

check_group(group)

Check the generator’s group.

Parameters:

group (Group): The group instance.

Returns:

valid (bool): Whether the given group is a valid EmptyGroup.
message (str): The reason why the group is not valid, empty string if valid.

set_maximum_collected(maximumCollected)

Set maximum collected number of atoms allowed.

Parameters:

maximumCollected (None, Integer): The maximum number allowed of atoms to be removed and collected from atomic configuration by the stochastic engine. This property is general to the system and checks engine’s collected atoms not the number of removed atoms via this generator. If None is given, the remover will not check for the number of already removed atoms before attempting a remove.

set_allow_fitting_scale_factor(allowFittingScaleFactor)

Set allow fitting scale factor flag.

Parameters:

allowFittingScaleFactor (bool): Constraints and especially experimental ones have a scale factor constant that can be fit. Fitting a scale factor happens at stochastic engine’s runtime at a certain fitting frequency. If this flag set to True, then fitting the scale factor will be allowed upon removing atoms. When set to False, fitting the constraint scale factor will be forbidden upon removing atoms. By default, allowFittingScaleFactor is set to False because it’s more logical to allow removing only atoms that enhances the total standard error without rescaling the model’s data.

set_atoms_list(atomsList)

Set atoms index list from which atoms will be picked to attempt removal. This method must be overloaded and not be called from this class but from its children. Otherwise a usage error will be raised.

Parameters:

atomsList (None, list,set,tuple,np.ndarray): The list of atoms index to chose and remove from.

move(coordinates, _resetRuntimeData=True)

Moves coordinates. This method must NOT be overloaded in MoveGenerator sub-classes.

Parameters:

coordinates (np.ndarray): Not used here.
_resetRuntimeData (bool): Not used here, present only for interface compatibility with MoveGenerator.move.

transform_coordinates(coordinates, argument)

This method must NOT be overloaded in MoveGenerator sub-classes.

Parameters:

coordinates (np.ndarray): Not used here.
argument (object): Not used here.

pick_from_list(engine)

This method must be overloaded in all RemoveGenerator sub-classes.

Parameters:

engine (Engine): stochastic engine calling the method.

class fullrmc.Core.MoveGenerator.SwapGenerator(group=None, swapLength=1, swapList=None)

Bases: MoveGenerator

It is a particular move generator that instead of generating a move upon a group of atoms, it will exchange the group atom positions with other atoms from a defined swapList. Because the swapList can be big, swapGenerator can be assigned to multiple groups at the same time under the condition of all groups having the same length.

During stochastic engine runtime, whenever a swap generator is encountered, all sophisticated selection recurrence modes such as (refining, exploring) will be reduced to simple recurrence.

This class can’t be instantiated but its sub-classes might be.

Parameters:

group (None, Group): The group instance.
swapLength (Integer): The swap length that defines the length of the group and the length of the every swap sub-list in swapList.
swapList (None, List): List of atoms index. If None is given, no swapping or exchanging will be performed. If List is given, it must contain lists of atom indexes where every sub-list must have the same number of atoms as the group.

property swapLength

Swap length.

Returns:

swapLength (integer): The swap length value.

property swapList

Swap list.

Returns:

swapList (tuple): The tuple of atoms indexes sub-lists to swap with.

property groupAtomsIndexes

Last selected group atoms index.

Returns:

groupAtomsIndexes (None, np.ndarray): The last selected group’s atoms indexes.

property swapAtomsIndexes

Last swap atoms index.

Returns:

swapAtomsIndexes (None, np.ndarray): The last atoms indexes swapped in.

property swapItemIndex

Last swap item index in remaining swapList.

Returns:

swapItemIndex (None, integer): The last used index in the remaining swapList.

set_swap_length(swapLength)

Set swap length. it will empty and reset swaplist automatically.

Parameters:

swapLength (Integer): The swap length that defines the length of the group and the length of the every swap sub-list in swapList.

set_group(group)

Set the MoveGenerator group.

Parameters:

group (None, Group): group instance.

set_swap_list(swapList)

Set the swap-list to exchange atoms position from.

Parameters:

swapList (None, List): The list of atoms.

If None is given, no swapping or exchanging will be performed.

If List is given, it must contain lists of atom indexes where every sub-list length must be equal to swapLength.

append_to_swap_list(subList)

Append a sub list to swap list.

Parameters:

subList (List): The sub-list of atoms index to append to swapList.

get_ready_for_move(engine, groupAtomsIndexes)

Set the swap generator ready to perform a move. Unlike a normal move generator, swap generators will affect not only the selected atoms but other atoms as well. Therefore at stochastic engine runtime, selected atoms will be extended to all affected atoms by the swap.

This method is called automatically upon stochastic engine runtime to ensure that all affected atoms with the swap are updated.

Parameters:

engine (fullrmc.Engine): The stochastic engine calling for the move.
groupAtomsIndexes (numpy.ndarray): The atoms index to swap.

Returns:

indexes (numpy.ndarray): All the atoms involved in the swap move including the given groupAtomsIndexes.

class fullrmc.Core.MoveGenerator.PathGenerator(group=None, path=None, randomize=False)

Bases: MoveGenerator

PathGenerator is a MoveGenerator sub-class where moves definitions are pre-stored in a path and get pulled out at every move step.

This class can’t be instantiated but its sub-classes might be.

Parameters:

group (None, Group): The group instance.
path (None, list): The list of moves.
randomize (boolean): Whether to pull moves randomly from path or pull moves in order at every step.

property step

Current step number.

Returns:

step (integer): The current step number in the path.

property path

Path list of moves.

Returns:

path (list): The normalized list of moves.

property randomize

Randomize flag.

Returns:

randomize (bool): Whether moves are pulled randomly from the path.

check_path(path)

Check the generator’s path.

This method must be overloaded in all PathGenerator sub-classes.

Parameters:

path (list): The list of moves.

normalize_path(path)

Normalizes all path moves. It is called automatically upon set_path method is called.

This method can be overloaded in all MoveGenerator sub-classes.

Parameters:

path (list): The list of moves.

Returns:

path (list): The list of moves.

set_path(path)

Set the moves path.

Parameters:

path (list): The list of moves.

set_randomize(randomize)

Set whether to randomize moves selection.

Parameters:

randomize (boolean): Whether to pull moves randomly from path or pull moves in order at every step.

move(coordinates, _resetRuntimeData=True)

Move coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the transformation.
_resetRuntimeData (bool): Internal fullrmc engine flag. When True (default), the generator’s runtimeData dictionary is cleared before applying the move. End users should not need to alter this.

Returns:

coordinates (np.ndarray): The new coordinates after applying the transformation.

class fullrmc.Core.MoveGenerator.MoveGeneratorCombinator(group=None, combination=None, shuffle=False)

Bases: MoveGenerator

MoveGeneratorCombinator combines all moves of a list of MoveGenerators and applies it at once.

Parameters:

group (None, Group): The constraint stochastic engine.
combination (list): The list of MoveGenerator instances.
shuffle (boolean): Whether to shuffle generator instances at every move or to combine moves in the list order.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Core.MoveGenerator import MoveGeneratorCombinator
from fullrmc.Generators.Translations import TranslationGenerator
from fullrmc.Generators.Rotations import RotationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...

##### Define each group move generator as a combination of a translation and a rotation. #####
# create recursive group selector. Recurrence is set to 20 with explore flag set to True.
# shuffle is set to True which means that at every selection the order of move generation
# is random. At one step a translation is performed prior to rotation and in another step
# the rotation is performed at first.
# selected from the collector.
for g in ENGINE.groups:
    # create translation generator
    TMG = TranslationGenerator(amplitude=0.2)
    # create rotation generator only when group length is bigger than 1.
    if len(g)>1:
        RMG = RotationGenerator(amplitude=2)
        MG  = MoveGeneratorCombinator(combination=[TMG,RMG],shuffle=True)
    else:
        MG  = MoveGeneratorCombinator(combination=[TMG],shuffle=True)
    g.set_move_generator( MG )

classmethod create(params, *args, **kwargs)

Create a selector instance given instantiation parameters

Parameters:

params (dict): instantiation parameters

Returns:

obj (Selector): the created instance

property parameters

Get current state and instantiation parameters.

Returns:

parameters (dict): A dictionary holding the class definition name, the combined generators’ own parameters and the shuffle constructor keyword argument.

property shuffle

Shuffle flag.

Returns:

shuffle (bool): Whether the combination order is shuffled at every move.

property combination

Combination list of MoveGenerator instances.

Returns:

combination (list): The list of combined MoveGenerator instances.

check_group(group)

Checks the generator’s group. This methods always returns True because normally all combination MoveGenerator instances groups are checked.

This method must NOT be overloaded unless needed.

Parameters:

group (Group): the Group instance

Returns:

valid (bool): Always True.
message (str): Always an empty string.

set_group(group)

Set the MoveGenerator group.

Parameters:

group (None, Group): group instance.

set_combination(combination)

Set the generators combination list.

Parameters:

combination (list): The list of MoveGenerator instances.

set_shuffle(shuffle)

Set whether to shuffle moves generator.

Parameters:

shuffle (boolean): Whether to shuffle generator instances at every move or to combine moves in the list order.

move(coordinates, _resetRuntimeData=True)

Move coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the transformation.
_resetRuntimeData (bool): Internal fullrmc engine flag. When True (default), the generator’s runtimeData dictionary is cleared before applying the move. End users should not need to alter this.

Returns:

coordinates (np.ndarray): The new coordinates after applying the transformation.

class fullrmc.Core.MoveGenerator.MoveGeneratorCollector(group=None, collection=None, randomize=True, weights=None)

Bases: MoveGenerator

MoveGeneratorCollector collects MoveGenerators instances and applies the move of one instance at every step.

Parameters:

group (None, Group): The constraint stochastic engine.
collection (list): The list of MoveGenerator instances.
randomize (boolean): Whether to pull MoveGenerator instance randomly from collection list or in order.
weights (None, list): Generators selections Weights list. It must be None for equivalent weighting or list of (generatorIndex, weight) tuples. If randomize is False, weights list is ignored upon generator selection from collection.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Core.MoveGenerator import MoveGeneratorCollector
from fullrmc.Generators.Translations import TranslationGenerator
from fullrmc.Generators.Rotations import RotationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...

##### Define each group move generator as a combination of a translation and a rotation. #####
# create recursive group selector. Recurrence is set to 20 with explore flag set to True.
# randomize is set to True which means that at every selection a generator is randomly
# selected from the collector.
for g in ENGINE.groups:
    # create translation generator
    TMG = TranslationGenerator(amplitude=0.2)
    # create rotation generator only when group length is bigger than 1.
    if len(g)>1:
        RMG = RotationGenerator(amplitude=2)
        MG  = MoveGeneratorCollector(collection=[TMG,RMG],randomize=True)
    else:
        MG  = MoveGeneratorCollector(collection=[TMG],randomize=True)
    g.set_move_generator( MG )

classmethod create(params, *args, **kwargs)

Create a selector instance given instantiation parameters

Parameters:

params (dict): instantiation parameters

Returns:

obj (Selector): the created instance

property parameters

Get current state and instantiation parameters.

Returns:

parameters (dict): A dictionary holding the class definition name, the collected generators’ own parameters, the non-default selection weights and the randomize constructor keyword argument.

property randomize

Randomize flag.

Returns:

randomize (bool): Whether a generator is pulled randomly from the collection at every move.

property collection

List of MoveGenerator instances.

Returns:

collection (list): The collected MoveGenerator instances.

property generatorsWeight

Generators selection weights list.

Returns:

generatorsWeight (list): The per-generator selection weight values.

property selectionScheme

Selection scheme.

Returns:

selectionScheme (np.ndarray): The cumulative weights array used to randomly draw a generator index at runtime.

set_group(group)

Set the MoveGenerator group.

Parameters:

group (None, Group): group instance.

check_group(group)

Check the generator’s group. This methods always returns True because normally all collection MoveGenerator instances groups are checked.

This method must NOT be overloaded unless needed.

Parameters:

group (Group): the Group instance.

Returns:

valid (bool): Always True.
message (str): Always an empty string.

set_collection(collection)

Set the generators instances collection list.

Parameters:

collection (list): The list of move generator instance.

set_randomize(randomize)

Set whether to randomize MoveGenerator instance selection from collection list.

Parameters:

randomize (boolean): Whether to pull MoveGenerator instance randomly from collection list or in order.

set_weights(weights)

Set groups selection weighting scheme.

Parameters:

weights (None, list): Generators selections Weights list. It must be None for equivalent weighting or list of (generatorIndex, weight) tuples. If randomize is False, weights list is ignored upon generator selection from collection.

set_selection_scheme(): Set selection scheme.

move(coordinates, _resetRuntimeData=True)

Move coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the transformation.
_resetRuntimeData (bool): Internal fullrmc engine flag. When True (default), the generator’s runtimeData dictionary is cleared before applying the move. End users should not need to alter this.

Returns:

coordinates (np.ndarray): The new coordinates after applying the transformation.

fullrmc.Generators package¶

Walks¶

Walks contains all random-walk like MoveGenerator classes.

fullrmc.Generators.Walks.generate_random_float()¶: random() -> x in the interval [0, 1).

class fullrmc.Generators.Walks.WalkGenerator(group=None, distance=0.2, angle=2)¶

Bases: MoveGenerator

Generate random walk moves upon groups of atoms. Random walks are a combination of a rotation and a translation. For one atom groups, only translations will be made

Parameters:

group (None, Group): The group instance.
distance (number): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple of length 2 is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min. If tuple of length 3 is given, it must be the limits in X, Y and Z directions given as numbers or tuples of length 2
angle (number): The maximum rotation angle allowed in degrees. It must be strictly bigger than 0 and strictly smaller than 360.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Walks import WalkGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random rotations.
# Maximum rotation amplitude is set to 5 degrees to all defined groups
for g in ENGINE.groups:
    g.set_move_generator( WalkGenerator(distance=1, angle=5) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

property distance¶

Translation distance limits.

Returns:

distance (tuple): The (min, max) translation distance limits in Angstroms.

property angle¶

Maximum allowed angle of rotation in rad.

Returns:

angle (number): The maximum allowed rotation angle in radians.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

set_distance(distance)¶

Set maximum translation vector allowed amplitude.

Parameters:

distance (number, tuple): The translation distance in Angstroms. If number is given, it is the maximum translation distance in Angstroms and must be bigger than 0. If tuple of length 2 is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min. If tuple of length 3 is given, it must be the limits in X, Y and Z directions given as numbers or tuples of length 2

set_angle(angle)¶

Set maximum rotation angle in degrees and transforms it to rad.

Parameters:

angle (number): the maximum allowed rotation angle in degrees. It must be strictly bigger than 0 and strictly smaller than 360.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Translate and rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

Translations¶

Translations contains all translation like MoveGenerator classes.

Random translation vectors generated from atom at origin. (`TranslationRandomGenerator`)¶	Random translation vectors generated from atom at origin along a pre-defined axis. (`TranslationAlongAxisGenerator`)¶
Random translation vector generated along a predefined axis or one of the symmetry axes of the hexane molecule and applied on all the molecule’s atoms at the same time. (`TranslationAlongAxisGenerator` `TranslationAlongSymmetryAxisGenerator`)¶	Random translation vectors generated towards an axis within some maximum angle. Legend is formatted as axis (angle) (direction) (`TranslationTowardsAxisGenerator` `TranslationTowardsSymmetryAxisGenerator`)¶
Random translation vectors generated towards a pre-defined center or towards the geometric center of a group of atoms. Here 20 vectors are generated within a maximum separation angle of 30 deg. (`TranslationTowardsCenterGenerator`)¶

fullrmc.Generators.Translations.generate_random_float()¶: random() -> x in the interval [0, 1).

class fullrmc.Generators.Translations.TranslationGenerator(*args, **kwargs)¶

Bases: MoveGenerator, AxisUtils, AmplitudeUtils

Generates translations moves upon groups of atoms. Translations can be random or along axis with or without tolerance angle.

Parameters:

group (None, Group): The group instance.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple of length 2 is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min. If tuple of length 3 is given, it must be the limits in X, Y and Z directions given as numbers or tuples of length 2
axis (None, integer,set,list,tuple,numpy.ndarray,dict): Translation axis vector. If integer, it must be 0,1 or 2 indicating the symmetry axis of translation which will be computed everytime at engine runtime If set, it will contain the atoms indexes to compute a center and then translation axis will be pointing from the coordinates center to the listed atoms center If list,tuple,numpy.ndarray it must be of length three which is a fixed axis If a dict is given, then it must contain a type and a value. type can be ‘symmetry_axis’ similar to integer, ‘to_atoms_center’ similar to set or ‘fixed_axis’ similar to list. ‘from_to’ is another axis type, where the value is a dict containing two keys ‘from’ and ‘to’ and the values of those are a dictionary containing a single key of value ‘atoms’, ‘group’ or ‘coords’ and the value must be a list of indexes. Another key can be given ‘fixed’, the value must be a a list of three numbers.
direction (‘same’, ‘opposite’, ‘any’, dict): Whether to generate translation vector in the same direction of axis or not. If ‘same’ all generated vectors are in the same direction of axis. If ‘opposite’ all generated vectors are in the opposite direction of axis. If ‘any’ generated axis can be in the same direction of axis or in the opposite. If dict is given, keys can be ‘same’, ‘opposite’, ‘any’, ‘set 1’ and ‘set 2’. the values must be lists of atoms in the group indexes ranging from 0 to the number of atoms in the group. atoms in ‘same’ will be translated in the same direction as the vector, ‘opposite’ in the opposite direction and ‘any’ will be all translated in any of the directions same or opposite. atoms listed in ‘set 1’ and ‘set 2’ will be randomly translated in different directions e.g. if ‘set 1’ are translated in the same direction, ‘set 2’ will be translated in the opposite direction and vice-versa
angle (None, number): The maximum tolerance angle in degrees between a generated translation vector and the pre-defined axis.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random translations.
# Maximum translation amplitude is set to 0.3A to all defined groups
for g in ENGINE.groups:
    g.set_move_generator( TranslationGenerator(amplitude = 0.3,
                                               axis      = {'type': 'to_atoms_center', 'value': [8, 9, 10, 11]},
                                               direction = {'same':[0], 'any':[3,4], 'set 1':[1], 'set 2':[2]}),
                                               angle     = 30 )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationRandomGenerator(group=None, amplitude=0.2)¶

Bases: MoveGenerator

Generates random translations moves upon groups of atoms.

Parameters:

group (None, Group): The group instance.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple of length 2 is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min. If tuple of length 3 is given, it must be the limits in X, Y and Z directions given as numbers or tuples of length 2

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationRandomGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random translations.
# Maximum translation amplitude is set to 0.3A to all defined groups
for g in ENGINE.groups:
    g.set_move_generator( TranslationRandomGenerator(amplitude=0.3) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property amplitude¶

Translation amplitude limits.

Returns:

amplitude (tuple): The (min, max) translation amplitude limits.

set_amplitude(amplitude)¶

Set maximum translation vector allowed amplitude.

Parameters:

amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple of length 2 is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min. If tuple of length 3 is given, it must be the limits in X, Y and Z directions given as numbers or tuples of length 2

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid. Always True for this generator.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationAlongAxisGenerator(group=None, amplitude=0.2, axis=(1, 0, 0), direction=None)¶

Bases: TranslationRandomGenerator

Generates random translation moves upon groups of atoms along a pre-defined axis.

Parameters:

group (None, Group): The group instance.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min.
axis (list,set,tuple,numpy.ndarray): The pre-defined translation axis vector.
direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None is given, generated axis can be in the same direction of axis or in the opposite. If True is given, all generated vectors are in the same direction of axis. If False is given, all generated vectors are in the opposite direction of axis.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationAlongAxisGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations along pre-defined axis (1,1,1).
# Maximum translation amplitude is set to 0.3A to all defined groups
for g in ENGINE.groups:
    g.set_move_generator( TranslationAlongAxisGenerator(amplitude=0.3, axis=(1,1,1)) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Translation axis.

Returns:

axis (numpy.ndarray): The normalized translation axis vector.

property direction¶

Generated translation vectors direction.

Returns:

direction (None, boolean): The translation direction restriction.

set_axis(axis)¶

Set the axis along which the translation will be performed.

Parameters:

axis (list,set,tuple,numpy.ndarray): Translation axis vector.

set_direction(direction)¶

Sets the generated translation vectors direction.

Parameters:

direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True all generated vectors are in the same direction of axis. If False all generated vectors are in the opposite direction of axis.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationTowardsAxisGenerator(group=None, amplitude=0.2, axis=(1, 0, 0), angle=30, direction=True)¶

Bases: TranslationAlongAxisGenerator

Generates random translation moves upon groups of atoms towards a pre-defined axis within a tolerance angle between translation vectors and the pre-defined axis.

Parameters:

group (None, Group): The group instance.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min.
axis (list,set,tuple,numpy.ndarray): The pre-defined translation axis vector.
angle (number): The maximum tolerance angle in degrees between a generated translation vector and the pre-defined axis.
direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True all generated vectors are in the same direction of axis. If False all generated vectors are in the opposite direction of axis.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationTowardsAxisGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations towards a pre-defined axis (1,1,1) within 10 degrees.
# Maximum translation amplitude is set to 0.3A to all defined groups
for g in ENGINE.groups:
    g.set_move_generator( TranslationTowardsAxisGenerator(amplitude=0.3, axis=(1,1,1), angle=10) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property angle¶

Tolerance maximum angle in rad.

Returns:

angle (number): The maximum tolerance angle in radians.

set_angle(angle)¶

Set the tolerance maximum angle.

Parameters:

angle (number): The maximum tolerance angle in degrees between a generated translation vector and the pre-defined axis.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationAlongSymmetryAxisGenerator(group=None, amplitude=0.2, axis=0, direction=None)¶

Bases: TranslationRandomGenerator

Generate random translation moves upon groups of atoms along one of their symmetry axis. Only groups containing more than 1 atoms allow computing symmetry axis.

Parameters:

group (None, Group): The group instance.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min.
axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis.
direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True all generated vectors are in the same direction of axis. If False all generated vectors are in the opposite direction of axis.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationAlongSymmetryAxisGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations along the second symmetry axis of every group.
# Maximum translation amplitude is set to 0.3A to all defined groups.
for g in ENGINE.groups:
    if len(g)>1:
        g.set_move_generator( TranslationAlongSymmetryAxisGenerator(amplitude=0.3, axis=1) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Translation axis index.

Returns:

axis (integer): The symmetry axis index used for translation.

property direction¶

Generated translation vectors direction.

Returns:

direction (None, boolean): The translation direction restriction.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_axis(axis)¶

Set the symmetry axis index to translate along.

Parameters:

axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis

set_direction(direction)¶

Sets the generated translation vectors direction.

Parameters:

direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True all generated vectors are in the same direction of axis. If False all generated vectors are in the opposite direction of axis.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationTowardsSymmetryAxisGenerator(group=None, amplitude=0.2, axis=0, angle=30, direction=True)¶

Bases: TranslationAlongSymmetryAxisGenerator

Generates random translation moves upon groups of atoms towards one of its symmetry axis within a tolerance angle between translation vectors and the axis. Only groups of more than 1 atom are accepted.

Parameters:

group (None, Group): The group instance.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min.
axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis.
angle (number): The maximum tolerance angle in degrees between a generated translation vector and the pre-defined axis.
direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True all generated vectors are in the same direction of axis. If False all generated vectors are in the opposite direction of axis.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationTowardsSymmetryAxisGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations towards the first symmetry axis of every group within 15 degrees.
# Maximum translation amplitude is set to 0.3A to all defined groups.
for g in ENGINE.groups:
    if len(g)>1:
        g.set_move_generator( TranslationTowardsSymmetryAxisGenerator(amplitude=0.3, axis=0, angle=15) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property angle¶

Tolerance maximum angle in rad.

Returns:

angle (number): The maximum tolerance angle in radians.

set_angle(angle)¶

Set the tolerance maximum angle.

Parameters:

angle (number): The maximum tolerance angle in degrees between a generated translation vector and the pre-defined axis.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationAlongSymmetryAxisPath(group=None, axis=0, path=None, randomize=False)¶

Bases: PathGenerator

Generates translation moves upon groups of atoms along one of their symmetry axis. Only groups of more than 1 atom are accepted.

Parameters:

group (None, Group): The group instance.
axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis
path (List): List of distances.
randomize (boolean): Whether to pull moves randomly from path or pull moves in order at every step.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationAlongSymmetryAxisPath

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations of predefined amplitudes along the first symmetry axis of every group.
amps = [-0.1, 0.075, -0.05, -0.25, 0.01, 0.02, 0.03, 0.1, 0.3]
for g in ENGINE.groups:
    if len(g)>1:
        g.set_move_generator( TranslationAlongSymmetryAxisPath(axis=0, path=amps) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Translation axis index.

Returns:

axis (integer): The symmetry axis index used for translation.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): The Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_axis(axis)¶

Set the symmetry axis index to translate along.

Parameters:

axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis

check_path(path)¶

Check the generator’s path.

Parameters:

path (None, list): The list of moves.

Returns:

result (boolean): Whether the path is valid.
message (string): Error message if result is False, empty string otherwise.

normalize_path(path)¶

Transforms all path distances to floating numbers.

Parameters:

path (list): The list of moves.

Returns:

path (list): The list of moves.

transform_coordinates(coordinates, argument)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (float): The move distance.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Translations.TranslationTowardsCenterGenerator(group=None, center={'fixed': (0, 0, 0)}, amplitude=0.1, angle=30, direction=True)¶

Bases: TranslationRandomGenerator

Generates random translation moves of every atom of the group along its direction vector to the geometric center of the group.

Parameters:

group (None, Group): The group instance.
center (dict): The center value dictionary. Must have a single key and this can only be ‘fixed’ or ‘indexes’. If key is fixed, value must be a list or a numpy.array of a point coordinates such as [X,Y,Z]. If key is indexes, value must be a list or a numpy array of indexes.
amplitude (number, tuple): The translation amplitude in Angstroms. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min.
angle (None, number): The maximum tolerance angle in degrees between a generated translation vector and the computed direction. If None is given, all generated translation vectors will be along the direction to center.
direction (None, True, False): Whether to generate translation vectors pointing towards the center or not. If None generated axis can be randomly generated towards the center or away from the center. If True is given, all generated vectors point towards the center. If False is given, all generated vectors point away from the center.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Translations import TranslationTowardsCenterGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations towards the origin defined as (0,0,0) within 20 degrees.
# Maximum translation amplitude is set to 0.2A to all defined groups.
for g in ENGINE.groups:
    g.set_move_generator( TranslationTowardsCenterGenerator(amplitude=0.2, center={"fixed":(0,0,0)}, angle=25) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property direction¶

Direction value.

Returns:

direction (None, boolean): The translation direction restriction.

property center¶

Center value.

Returns:

center (dict): The center value or definition dictionary.

property angle¶

Angle value in rad.

Returns:

angle (None, number): The maximum tolerance angle in radians.

set_direction(direction)¶

Set the generated translation vectors direction.

Parameters:

direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True is given, all generated vectors are in the same direction of axis. If False is given, all generated vectors are in the opposite direction of axis.

set_angle(angle)¶

Sets the tolerance maximum angle.

Parameters:

angle (None, number): The maximum tolerance angle in degrees between a generated translation vector and the computed direction. If None is given, all generated translation vectors will be along the direction to center.

set_center(center)¶

Set center value.

Parameters:

center (dict): The center value dictionary. Must have a single key and this can only be ‘fixed’ or ‘indexes’. If key is fixed, value must be a list or a numpy.array of a point coordinates such as [X,Y,Z]. If key is indexes, value must be a list or a numpy array of indexes.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

Rotations¶

Rotations contains all rotation like MoveGenerator classes.

Random rotation axis and angle generated and applied on a Tetrahydrofuran molecule. Solid colours are of the origin molecule position while fading ones are of the rotated molecule. (`RotationGenerator`)¶	Random rotation generated about a pre-defined axis or one of the symmetry axes of the Tetrahydrofuran molecule. Solid colours are of the origin molecule position while fading ones are of the rotated molecule. (`RotationAboutAxisGenerator` `RotationAboutSymmetryAxisGenerator`)¶
Random orientation of hexane molecule to [1,1,1] axis with maximumOffsetAngle of 10 degrees is generated. First principal axis of hexane molecule is considered as groupAxis. Solid colors are of original molecule while fading ones are of the oriented one. (`OrientationGenerator`)¶

fullrmc.Generators.Rotations.generate_random_float()¶: random() -> x in the interval [0, 1).

class fullrmc.Generators.Rotations.RotationGenerator(*args, **kwargs)¶

Bases: MoveGenerator, AxisUtils

Generates random rotational moves upon groups of atoms about a random or pre-defined axis.

Parameters:

group (None, Group): The group instance.
amplitude (number): The maximum allowed rotation angle in degrees. It must be strictly bigger than 0 and strictly smaller than 360.
axis (None, list,set,tuple,numpy.ndarray, dict): The rotational axis vector.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Rotations import RotationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random rotations about (1,1,1) a pre-defined axis.
# Maximum rotation amplitude is set to 5 degrees to all defined groups
for g in ENGINE.groups:
    if len(g) >1:
        g.set_move_generator( RotationGenerator(amplitude=5, axis=(1,1,1)) )

property amplitude¶

Maximum allowed angle of rotation in rad.

Returns:

amplitude (number): The maximum allowed rotation angle in radians.

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

set_amplitude(amplitude)¶

Set maximum rotation angle in degrees and transforms it to rad.

Parameters:

amplitude (number): the maximum allowed rotation angle in degrees. It must be strictly bigger than 0 and strictly smaller than 360.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

class fullrmc.Generators.Rotations.RotationRandomGenerator(group=None, amplitude=2)¶

Bases: MoveGenerator

Generate random rotational moves upon groups of atoms. Only groups of more than one atom are accepted.

Parameters:

group (None, Group): The group instance.
amplitude (number): The maximum rotation angle allowed in degrees. It must be strictly bigger than 0 and strictly smaller than 360.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Rotations import RotationRandomGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random rotations.
# Maximum rotation amplitude is set to 5 degrees to all defined groups
for g in ENGINE.groups:
    if len(g) >1:
        g.set_move_generator( RotationRandomGenerator(amplitude=5) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

property amplitude¶

Maximum allowed angle of rotation in rad.

Returns:

amplitude (number): The maximum allowed rotation angle in radians.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

set_amplitude(amplitude)¶

Set maximum rotation angle in degrees and transforms it to rad.

Parameters:

amplitude (number): the maximum allowed rotation angle in degrees. It must be strictly bigger than 0 and strictly smaller than 360.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

class fullrmc.Generators.Rotations.RotationAboutAxisGenerator(group=None, amplitude=2, axis=(1, 0, 0))¶

Bases: RotationRandomGenerator

Generates random rotational moves upon groups of atoms about a pre-defined axis.

Parameters:

group (None, Group): The group instance.
amplitude (number): The maximum allowed rotation angle in degrees. It must be strictly bigger than 0 and strictly smaller than 360.
axis (list,set,tuple,numpy.ndarray): The rotational axis vector.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Rotations import RotationAboutAxisGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random rotations about (1,1,1) a pre-defined axis.
# Maximum rotation amplitude is set to 5 degrees to all defined groups
for g in ENGINE.groups:
    if len(g) >1:
        g.set_move_generator( RotationAboutAxisGenerator(amplitude=5, axis=(1,1,1)) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Rotation axis vector.

Returns:

axis (numpy.ndarray): The normalized rotation axis vector.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): The Group instance.

Returns:

result (boolean): Whether the group is valid. Always True for this generator.
message (string): Error message if result is False, empty string otherwise.

set_axis(axis)¶

Set the axis along which the rotation will be performed.

Parameters:

axis (list,set,tuple,numpy.ndarray): The rotation axis vector.

transform_coordinates(coordinates, argument=None)¶

Rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

class fullrmc.Generators.Rotations.RotationAboutSymmetryAxisGenerator(group=None, amplitude=2, axis=0)¶

Bases: RotationRandomGenerator

Generates random rotational moves upon groups of atoms about one of their symmetry axis. Only groups of more than 1 atom are accepted.

Parameters:

group (None, Group): The group instance.
amplitude (number): Maximum rotation angle in degrees. It must be strictly bigger than 0 and strictly smaller than 360.
axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Rotations import RotationAboutSymmetryAxisGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random rotations about the second symmetry axis of each group.
# Maximum rotation amplitude is set to 5 degrees to all defined groups
for g in ENGINE.groups:
    if len(g) >1:
        g.set_move_generator( RotationAboutSymmetryAxisGenerator(amplitude=5, axis=1) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Rotation axis index.

Returns:

axis (integer): The symmetry axis index used for rotation.

set_axis(axis)¶

Set the symmetry axis index to rotate about.

Parameters:

axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis.

transform_coordinates(coordinates, argument=None)¶

Rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

class fullrmc.Generators.Rotations.RotationAboutSymmetryAxisPath(group=None, axis=0, path=None, randomize=False)¶

Bases: PathGenerator

Generate rotational moves upon groups of atoms about one of their symmetry axis. Only groups of more than one atom are accepted.

Parameters:

group (None, Group): The group instance.
axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis.
path (List): list of angles.
randomize (boolean): Whether to pull moves randomly from path or pull moves in order at every step.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Rotations import RotationAboutSymmetryAxisPath

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to pre-defined rotations about the second symmetry axis of each group.
angles = [-0.1, -0.5, -0.05, 0.5, 0.01, 2, 3, 1, -3]
for g in ENGINE.groups:
    if len(g) >1:
        g.set_move_generator( RotationAboutSymmetryAxisPath(axis=1, path=angles) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Rotation axis index.

Returns:

axis (integer): The symmetry axis index used for rotation.

set_axis(axis)¶

Set the symmetry axis index to rotate about.

Parameters:

axis (integer): Must be 0,1 or 2 for respectively the main, secondary or tertiary symmetry axis

check_path(path)¶

Check the generator’s path.

Parameters:

path (None, list): The list of moves.

Returns:

result (boolean): Whether the path is valid.
message (string): Error message if result is False, empty string otherwise.

normalize_path(path)¶

Transform all path angles to radian.

Parameters:

path (list): The list of moves in degrees.

Returns:

path (list): The list of moves in rad.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): The rotation angle.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

class fullrmc.Generators.Rotations.OrientationGenerator(group=None, maximumOffsetAngle=10, groupAxis={'symmetry': 0}, orientationAxis={'fixed': (1, 0, 0)}, flip=None)¶

Bases: MoveGenerator

Generate rotational moves upon groups of atoms to align and orient along an axis. Orientation rotations are computed randomly allowing offset angle between groupAxis and orientationAxis. Only groups of more than 1 atom are accepted.

Parameters:

group (None, Group): The group instance.
maximumOffsetAngle (number): The maximum offset angle in degrees between groupAxis and orientationAxis.
groupAxis (dict): The group axis. Only one key is allowed. If key is ‘fixed’, value must be a list, tuple or a numpy.array of a vector such as [X,Y,Z]. If key is ‘symmetry’, in this case the group axis is computed as one of the three symmetry axis of the group atoms. the value must be even 0, 1 or 2 for respectively the first, second and tertiary symmetry axis.
orientationAxis (dict): The axis to align the group with. If key is ‘fixed’, value must be a list, tuple or a numpy.array of a vector such as [X,Y,Z]. If Key is ‘symmetry’, in this case the value must be a list of two items, the first one is a list of atoms indexes to compute symmetry axis and the second item must be even 0, 1 or 2 for respectively the first, second and tertiary symmetry axis.
flip (None, bool): Whether to allow flipping axis orientation or not. If True, orientationAxis will be flipped forcing anti-parallel orientation. If False, orientationAxis will not be flipped forcing parallel orientation. If None is given, no flipping is forced, flipping can be set randomly to True or False during run time execution.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Rotations import OrientationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to orientations of each group third symmetry axis
# towards the (-1,0,2) the predefined axis within maximum 5 degrees.
for g in ENGINE.groups:
    if len(g) >1:
        g.set_move_generator( OrientationGenerator(maximumOffsetAngle=5,
                                                   groupAxis={"symmetry":2},
                                                   orientationAxis={"fixed":(-1,0,2)}) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property maximumOffsetAngle¶

Maximum offset angle allowed between groupAxis and orientationAxis, stored internally in radians.

Returns:

maximumOffsetAngle (number): The maximum offset angle in radians.

property orientationAxis¶

Orientation axis value or definition.

Returns:

orientationAxis (dict): The orientation axis value or definition.

property groupAxis¶

Group axis value or definition.

Returns:

groupAxis (dict): The group axis value or definition.

property flip¶

Flip value.

Returns:

flip (None, bool): The flip flag value.

set_maximum_offset_angle(maximumOffsetAngle)¶

Set the maximum offset angle allowed.

Parameters:

maximumOffsetAngle (number): The maximum offset angle in degrees between groupAxis and orientationAxis.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_flip(flip)¶

Set flip flag value.

Parameters:

flip (None, bool): Whether to allow flipping axis orientation or not. If True, orientationAxis will be flipped forcing anti-parallel orientation. If False, orientationAxis will not be flipped forcing parallel orientation. If None is given, no flipping is forced, flipping can be set randomly to True or False during run time execution.

set_group_axis(groupAxis)¶

Sets group axis value.

Parameters:

groupAxis (dict): The group axis. Only one key is allowed. If key is fixed, value must be a list, tuple or a numpy.array of a vector such as [X,Y,Z]. If key is symmetry, in this case the group axis is computed as one of the three symmetry axis of the group atoms. the value must be even 0, 1 or 2 for respectively the first, second and tertiary symmetry axis.

set_orientation_axis(orientationAxis)¶

Set orientation axis value.

Parameters:

orientationAxis (dict): The axis to align the group axis with. If key is fixed, value must be a list, tuple or a numpy.array of a vector such as [X,Y,Z]. If Key is symmetry, in this case the value must be a list of two items, the first one is a list of atoms indexes to compute symmetry axis and the second item must be even 0, 1 or 2 for respectively the first, second and tertiary symmetry axis.

transform_coordinates(coordinates, argument=None)¶

Rotate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the rotation.
argument (object): Not used here.

Returns:

coordinates (np.ndarray): The new coordinates after applying the rotation.

Volumes¶

Volumes contains all MoveGenerator classes that will generate moves within a predefined volume of space.

fullrmc.Generators.Volumes.generate_random_float()¶: random() -> x in the interval [0, 1).

class fullrmc.Generators.Volumes.VolumeGenerator(group=None, amplitude=None, center=None)¶

Bases: MoveGenerator

Generates random moves upon groups of atoms within the boundaries of a defined volume.

Parameters:

group (None, Group): The group instance.
amplitude (None, number, tuple): The translation amplitude in Angstroms of the group towards the randomly generated positions in the volume. If None, no translation will be made but simple respositioning of the group center towards the randomly created position within the boundaries of the predefined volume. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min.
center (list, tuple, numpy.ndarray): The volume center in the 3d space.

property center¶

Volume center.

Returns:

center (numpy.ndarray): The volume center coordinates.

property amplitude¶

Translation amplitude towards generated positions within the volume.

Returns:

amplitude (None, tuple): The (min, max) translation amplitude in Angstroms, or None.

set_center(center)¶

Set volume center

Parameters:

center (list, tuple, numpy.ndarray): The volume center in the 3d space. Depending on the concrete generator, this anchor point can represent different things, e.g. the geometric center of a sphere or the point through which a cylinder’s axis passes.

set_amplitude(amplitude)¶

Set maximum translation vector allowed amplitude.

Parameters:

amplitude (None, number, tuple): The translation amplitude in Angstroms of the group towards the randomly generated positions in the volume. If None, no translation will be made but simple respositioning of the group center towards the randomly created position within the boundaries of the predefined volume. If number is given, it is the maximum translation amplitude in Angstroms and must be bigger than 0. If tuple is given, it is the limits of translation boundaries as [min,max] where min>=0 and max>min

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Volumes.CylinderVolumeGenerator(radius=1, length=2, axis=(1, 0, 0), direction=None, *args, **kwargs)¶

Bases: VolumeGenerator

Generates random moves upon groups of atoms along within a predefined cylinder.

Parameters:

group (None, Group): The group instance.
amplitude (None, number, tuple): The translation amplitude in Angstroms of the group towards the randomly generated positions within the cylinder. See VolumeGenerator for full details.
center (list, tuple, numpy.ndarray): The cylinder center in the 3d space.
radius (number, list,tuple): The cylinder radius in angstrom. If list is given, it will be the minimum and maximum value of the radius.
length (number, list): the length of the cylinder. If a number is given, it will be considered the length for both positive and negative directions. If list is given, it must have 2 items where the first is the length in the negative direction of the axis from the center and the second is the length in the positive direction
axis (list,set,tuple,numpy.ndarray): The cylinder direction axis
direction (None, True, False): Whether to generate volume positions in the same direction of the volume axis or not. If None is given, generated axis can be in the same direction of axis or in the opposite. If True is given, all generated vectors are in the same direction of axis. If False is given, all generated vectors are in the opposite direction of axis.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Volumes import CylinderVolumeGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to translations along pre-defined axis (1,1,1).
for g in ENGINE.groups:
    g.set_move_generator( CylinderVolumeGenerator(center=np.mean(ENGINE.realCoordinates[g.indexes], axis=0),
                                                  axis=(1,1,1)) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property axis¶

Cylinder axis.

Returns:

axis (numpy.ndarray): The normalized cylinder axis vector.

property direction¶

Cylinder move direction.

Returns:

direction (None, boolean): The move direction restriction.

property length¶

Cylinder length.

Returns:

length (tuple): The (negative, positive) cylinder length values.

property radius¶

Cylinder radius.

Returns:

radius (tuple): The (min, max) cylinder radius values.

set_axis(axis)¶

Set the cylinder main axis

Parameters:

axis (list,set,tuple,numpy.ndarray): Translation axis vector.

set_length(length)¶

Set cylinder length from the negative and positive side of the axis

Parameters:

length (number, list): the length of the cylinder. If a number is given, it will be considered the length for both positive and negative directions. If list is given, it must have 2 items where the first is the length in the negative direction of the axis from the center and the second is the length in the positive direction

set_radius(radius)¶

set cylinder volume radius

Parameters:

radius (number, list,tuple): The cylinder radius in angstrom. If list is given, it will be the minimum and maximum value of the radius.

set_direction(direction)¶

Sets the generated translation vectors direction.

Parameters:

direction (None, True, False): Whether to generate volume moves along position axis direction, negating or both. If True all generated moves are in the same direction of axis. If False all generated moves are in the opposite direction of axis. If None moves will be generated at random in the axis direction or in the opposite direction

Neighbours¶

Neighbours contains all MoveGenerator definitions that dynamically create the atoms neighbouring list of a group and perform a move towards those.

fullrmc.Generators.Neighbours.generate_random_float()¶: random() -> x in the interval [0, 1).

class fullrmc.Generators.Neighbours.NeighboursGeneratorBase(group=None, numberOfNeighbours=1, filter=None, update=10)¶

Bases: MoveGenerator

Base implementation of all ‘Neighbours’ generators. This defintion is not allowed to be instanciated.

Parameters:

group (None, Group): The group instance.
numberOfNeighbours (integer): Number of neighbours to collect
filter (None, str, list, dict): atoms filter to be considered when finding the neighbours. If None, all atoms will be considered. If string, it will be the atom element. If list, it can be a list of integers of the atom indexes to consider or a list of elements. If a dict is given, it can contain all of ‘index’, ‘name’ or ‘element’ keys and values ar list of those to filter from
update (integer): the neighbour update frequency in number of moves generated

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property updateFrequency¶

Update frequency.

Returns:

updateFrequency (integer): The neighbour update frequency in number of moves generated.

property neighbours¶

Neighbours index list.

Returns:

neighbours (None, list): The currently collected neighbours index list, or None if not yet computed.

property numberOfNeighbours¶

Number of neighbours to collect.

Returns:

numberOfNeighbours (integer): The number of neighbours to collect.

property filter¶

Neighbour filter.

Returns:

filter (None, dict): The neighbours filter dictionary.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_number_of_neighbours(numberOfNeighbours)¶

Set the number of neighbours to collect

Parameters:

numberOfNeighbours (integer): Number of neighbours to collect

set_filter(filter)¶

set the neighbours filter

Parameters:

filter (None, str, list, dict): atoms filter to be considered when getting the neighbour. If None, all atoms will be considered. If string, it will be the atom element. If list, it can be a list of integers of the atom indexes to consider or a list of elements. If a dict is given, it can contain all of ‘index’, ‘name’ or ‘element’ keys and values ar list of those to filter from

set_update(update)¶

Set the neighbour update frequency.

Parameters:

update (integer): the neighbour update frequency in number of moves generated

update_neighbours()¶: Recompute and update the group’s neighbours list based on distance to the group’s geometric center, applying the currently set filter.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Neighbours.TranslationTowardsNeighboursGenerator(bottom=0.01, top=0.3, height=0.25, direction=None, *args, **kwargs)¶

Bases: NeighboursGeneratorBase

This move generator will perform random translation vectors from a truncated cone using generate_vectors_in_truncated_cone.

This implementation seems similar to TranslationTowardsCenterGenerator but they actually differ in the way the translation to center is computed. In this implementation the center is computed dynamically using the collected neighbours list of atoms. But in TranslationTowardsCenterGenerator the center is a known fixed set of atom indexes.

Along with all NeighboursGeneratorBase parameters the following can be set

Parameters:

bottom (number, tuple): the truncated cone bottom radius located centered around the group geometric center. If number is given, it is the maximum radius in Angstroms If tuple is given, it is the radius min and max [min,max] where min>=0 and max>=min.
top (number, tuple): the truncated cone top radius located centered away from the group geometric center. If number is given, it is the maximum radius in Angstroms If tuple is given, it is the radius min and max [min,max] where min>=0 and max>=min.
height (number, tuple): the truncated cone height. If number is given, it will be used as the maximum cylinder height. If tuple is given, it is the radius min and max [min,max] where min>=0 and max>=min.
direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True all generated vectors are in the same direction of axis. If False all generated vectors are in the opposite direction of axis.

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property direction¶

Direction value.

Returns:

direction (None, boolean): The translation direction restriction.

property height¶

Translation amplitude limits.

Returns:

height (tuple): The (min, max) truncated cone height.

property bottom¶

Translation bottom disk radius.

Returns:

bottom (tuple): The (min, max) bottom disk radius.

property top¶

Translation top disk radius.

Returns:

top (tuple): The (min, max) top disk radius.

set_direction(direction)¶

Set the generated translation vectors direction.

Parameters:

direction (None, True, False): Whether to generate translation vector in the same direction of axis or not. If None generated axis can be in the same direction of axis or in the opposite. If True is given, all generated vectors are in the same direction of axis. If False is given, all generated vectors are in the opposite direction of axis.

set_height(height)¶

Set the cylinder height.

Parameters:

height (number, tuple): the truncated cone height. If number is given, it will be used as the maximum cylinder height. If tuple is given, it is the radius min and max [min,max] where min>=0 and max>=min.

set_bottom(value)¶

Set the cylinder bottom radius.

Parameters:

value (number, tuple): the truncated cone bottom radius located centered around the group geometric center. If number is given, it is the maximum radius in Angstroms If tuple is given, it is the radius min and max [min,max] where min>=0 and max>=min.

set_top(value)¶

Set the cylinder top radius.

Parameters:

value (number, tuple): the truncated cone top radius located centered away from the group geometric center. If number is given, it is the maximum radius in Angstroms If tuple is given, it is the radius min and max [min,max] where min>=0 and max>=min.

Agitations¶

Agitations contains all MoveGenerator classes that agitate and shake structures such as distances, angles, etc.

_images/distanceAgitation.png — Random H-H bond length agitations generated on dihydrogen molecules. At room temperature, H2 molecule bond length fluctuates around 0.74 Angstroms. Red hydrogen atoms represent the shrank H-H bond length molecule while blue hydrogen atoms represent the expanded H-H bond length molecules.¶

(`DistanceAgitationGenerator`)

_images/angleAgitation.png — Random H-O-H angle agitation generated on water molecules. At room temperature, water molecule angle formed between the two vectors formed between consecutively the Oxygen atom and the two hydrogen atoms is about 105 deg. Shrank H-O-H angles are represented by the red hydrogen while expanded angles are represented in blue. (`AngleAgitationGenerator`)¶

fullrmc.Generators.Agitations.generate_random_float()¶: random() -> x in the interval [0, 1).

class fullrmc.Generators.Agitations.DistanceAgitationGenerator(group=None, amplitude=0.2, symmetric=True, shrink=None, agitate=(True, True))¶

Bases: MoveGenerator

Generates random agitation moves upon a distance separating two atoms by translating both atoms away from each other or closer to each other along the direction line between them. This is mainly used to shake two atoms bond distance by increasing and decreasing the bond length. Only groups of length 2 are accepted.

Parameters:

group (None, Group): The group instance. It must contain exactly two indexes.
amplitude (number): The maximum agitation amplitude in Angstroms applied on every atom.
symmetric (bool): Whether to apply the same amplitude of translation on both atoms or not.
shrink (None, bool): Whether to always shrink the distance or expand it. If True, moves will always bring atoms closer to each other. If False, moves will always bring atoms away from each other. If None, no orientation is forced, therefore atoms can randomly get closer to each other or away from each other.
agitate (tuple): It’s a tuple of two boolean values, at least one of them must be True. Whether to agitate the first atom, the second or both. This is useful to set an atom fixed while only the other succumb the agitation to adjust the distance. For instance in a C-H group it can be useful and logical to adjust the bond length by moving only the hydrogen atom along the bond direction.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Agitations import DistanceAgitationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random agitations of distance separating two atoms.
# Maximum agitation amplitude is set to 0.5A
for g in ENGINE.groups:
    if len(g)==2:
        g.set_move_generator( DistanceAgitationGenerator(amplitude=0.5) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property amplitude¶

Maximum agitation amplitude.

Returns:

amplitude (number): The maximum agitation amplitude in Angstroms.

property shrink¶

Shrink flag value.

Returns:

shrink (None, bool): The shrink flag value.

property symmetric¶

Symmetric flag value.

Returns:

symmetric (bool): The symmetric flag value.

property agitate¶

Agitate tuple flags value.

Returns:

agitate (tuple): The agitate tuple flags value.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_amplitude(amplitude)¶

Sets maximum translation vector allowed amplitude.

Parameters:

amplitude (number): the maximum allowed translation vector amplitude.

set_symmetric(symmetric)¶

Set symmetric flag value.

Parameters:

symmetric (bool): Whether to apply the same amplitude of translation on both atoms or not.

set_shrink(shrink)¶

Set shrink flag value.

Parameters:

shrink (None, bool): Whether to always shrink the distance or expand it. If True, moves will always bring atoms closer to each other. If False, moves will always bring atoms away from each other. If None, no orientation is forced, therefore distance can increase or decrease randomly at every step.

set_agitate(agitate)¶

Set agitate tuple value.

Parameters:

agitate (tuple): It’s a tuple of two boolean values, at least one of them must be True. Whether to agitate the first atom, the second or both. This is useful to set an atom fixed while only the other succumb the agitation to adjust the distance. For instance in a C-H group it can be useful and logical to adjust the bond length by moving only the hydrogen atom along the bond direction.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

class fullrmc.Generators.Agitations.AngleAgitationGenerator(group=None, amplitude=2, symmetric=True, shrink=None, agitate=(True, True))¶

Bases: MoveGenerator

Generate random agitation moves upon an angle defined between two vectors left-central and right-central where (central, left, right) are three atoms. Move will be performed on left and/or right atom while central atom will always remain fixed. Distances between left/right and central atoms will remain unchanged. This is mainly used to shake bonded atoms angles by increasing and decreasing the bond length. Only groups of length 3 are accepted.

Parameters:

group (None, Group): The group instance. It must contain exactly three indexes in respective order (central, left, right) atoms index.
amplitude (number): The maximum agitation angle amplitude in degrees of left and right atoms separately.
symmetric (bool): Whether to apply the same amplitude of rotation on both left and right atoms or not.
shrink (None, bool): Whether to always shrink the angle or expand it. If True, moves will always reduce angle. If False, moves will always increase angle. If None, no orientation is forced, therefore angle can randomly get wider or tighter.
agitate (tuple): It’s a tuple of two boolean values for respectively (left, right) atoms, at least one of them must be True. Whether to agitate the left atom, the right or both. This is useful to set an atom fixed while only the other succumb the agitation to adjust the angle.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Agitations import AngleAgitationGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

# set moves generators to random agitations of the angle formed between
# one central atom and other two. Maximum agitation amplitude is set to 10.
for g in ENGINE.groups:
    if len(g)==3:
        g.set_move_generator( AngleAgitationGenerator(amplitude=10) )

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property amplitude¶

Maximum agitation angle amplitude in rad.

Returns:

amplitude (number): The maximum agitation angle amplitude in radians.

property shrink¶

Shrink flag value.

Returns:

shrink (None, bool): The shrink flag value.

property symmetric¶

Symmetric flag value.

Returns:

symmetric (bool): The symmetric flag value.

property agitate¶

Agitate tuple flags value.

Returns:

agitate (tuple): The agitate tuple flags value.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_amplitude(amplitude)¶

Set maximum allowed agitation rotation angle amplitude in degrees of left and right atoms separately and transforms it to rad.

Parameters:

amplitude (number): The maximum agitation angle amplitude in degrees of left and right atoms separately.

set_symmetric(symmetric)¶

Set symmetric flag value.

Parameters:

symmetric (bool): Whether to apply the same amplitude of translation on both atoms or not.

set_shrink(shrink)¶

Set shrink flag value.

Parameters:

shrink (None, bool): Whether to always shrink the distance or expand it. If True, moves will always bring atoms closer to each other. If False, moves will always bring atoms away from each other. If None, no orientation is forced, therefore distance can increase or decrease randomly at every step.

set_agitate(agitate)¶

Set agitate tuple value.

Parameters:

agitate (tuple): It’s a tuple of two boolean values, at least one of them must be True. Whether to agitate the first atom, the second or both. This is useful to set an atom fixed while only the other succumb the agitation to adjust the distance. For instance in a C-H group it can be useful and logical to adjust the bond length by moving only the hydrogen atom along the bond direction.

transform_coordinates(coordinates, argument=None)¶

Translate coordinates.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the translation.
argument (object): Any python object. Not used in this generator.

Returns:

coordinates (np.ndarray): The new coordinates after applying the translation.

Swap¶

Swaps contains all swap or atoms position exchange MoveGenerator classes.

class fullrmc.Generators.Swaps.SwapPositionsGenerator(group=None, swapLength=1, swapList=None)¶

Bases: SwapGenerator

Generates positional swapping between atoms of the selected group and other atoms randomly selected from swapList.

Parameters:

group (None, Group): The group instance.
swapLength (Integer): The swap length that defines the length of the group and the length of every swap sub-list in swapList.
swapList (None, List): The list of atoms to swap with.

If None is given, no swapping or exchanging will be performed.

If List is given, it must contain lists of atoms where every sub-list must have the same number of atoms as the group.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Swaps import SwapPositionsGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

##### set swap moves between Lithium and Manganese atoms in Li2MnO3 system #####
# reset engine groups to atoms to ensure atomic grouping of all the system's atoms
ENGINE.set_groups_as_atoms()
# get all elements list
elements = ENGINE.allElements
# create list of lithium atoms indexes
liIndexes = [[idx] for idx in xrange(len(elements)) if elements[idx]=='li']
# create list of manganese atoms indexes
mnIndexes = [[idx] for idx in xrange(len(elements)) if elements[idx]=='mn']
# create swap generator to lithium atoms
swapWithLi = SwapPositionsGenerator(swapList=liIndexes)
# create swap generator to manganese atoms
swapWithMn = SwapPositionsGenerator(swapList=mnIndexes)
# set swap generator to groups
for g in ENGINE.groups:
    # get group's atom index
    idx = g.indexes[0]
    # set swap to manganese for lithium atoms
    if elements[idx]=='li':
        g.set_move_generator(swapWithMn)
    # set swap to lithium for manganese atoms
    elif elements[idx]=='mn':
        g.set_move_generator(swapWithLi)
    # the rest are oxygen atoms. Default RandomTranslation generator are kept.

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): The Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

set_swap_length(swapLength)¶

Set swap length. It will reset swaplist automatically.

Parameters:

swapLength (Integer): The swap length that defines the length of the group and the length of the every swap sub-list in swapList.

transform_coordinates(coordinates, argument=None)¶

Transform coordinates by swapping. This method is called in every move.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the swapping.
argument (object): Any other argument needed to perform the move. In general it’s not needed.

Returns:

coordinates (np.ndarray): The new coordinates after applying the move.

class fullrmc.Generators.Swaps.SwapCentersGenerator(group=None, swapList=None)¶

Bases: SwapGenerator

Computes geometric center of the selected group, and swaps its atoms by translation to the atoms geometric center of the other atoms which are randomly selected from swapList and vice-versa.

Parameters:

group (None, Group): The group instance.
swapList (None, List): The list of atoms to swap from.

If None is given, no swapping or exchanging will be performed.

If List is given, it must contain lists of atoms index.

# import fullrmc modules
from fullrmc.Engine import Engine
from fullrmc.Generators.Swaps import SwapCentersGenerator

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

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

# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...

##### set swap moves between first 10 molecular groups of a system #####
# reset engine groups to molecules
ENGINE.set_groups_as_molecules()
# set swap generator to the first 10 groups
GROUPS = [ENGINE.groups[idx] for idx in range(10)]
for gidx, group in enumerate(GROUPS):
    swapList = [g.indexes for idx,g in enumerate(GROUPS) if idx!=gidx]
    swapGen  = SwapCentersGenerator(swapList=swapList)
    group.set_move_generator(swapGen)

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

property swapLength¶

Swap length. In this Case it is always None as swapLength is not required for this generator.

Returns:

swapLength (None): Always None for this generator.

set_swap_length(swapLength)¶

Set swap length. The swap length that defines the length of the group and the length of the every swap sub-list in swapList. It will automatically be set to None as SwapCentersGenerator does not require a fixed length.

Parameters:

swapLength (None): The swap length.

set_group(group)¶

Set the MoveGenerator group.

Parameters:

group (None, Group): group instance.

check_group(group)¶

Check the generator’s group.

Parameters:

group (Group): the Group instance.

Returns:

result (boolean): Whether the group is valid.
message (string): Error message if result is False, empty string otherwise.

transform_coordinates(coordinates, argument=None)¶

Transform coordinates by swapping. This method is called in every move.

Parameters:

coordinates (np.ndarray): The coordinates on which to apply the swapping.
argument (object): Any other argument needed to perform the move. In general it’s not needed.

Returns:

coordinates (np.ndarray): The new coordinates after applying the move.

Removes¶

Removes contains move generators that remove atoms from the system rather than moving or transforming them.

class fullrmc.Generators.Removes.AtomsRemoveGenerator(group=None, maximumCollected=None, atomsList=None)¶

Bases: RemoveGenerator

This generator allows removing single atoms at a time from the system. Atoms are randomly picked from atomsList and returned upon calling pick_from_list method.

Parameters:

group (None, Group): The group instance which is this case must be fullrmc EmptyGroup.
maximumCollected (None, Integer): The maximum number of atoms allowed to be removed and collected from the engine. This property is general to the system and checks engine’s collected atoms not the number of removed atoms via this generator. If None is given, the remover will not check for the number of already removed atoms before attempting a remove.
atomsList (None, list,set,tuple,np.ndarray): The list of atoms index to chose and remove from. If None is given, then all atoms in system will be used.

classmethod create(params, *args, **kwargs)¶

Create a move generator instance given instantiation parameters

Parameters:

params (dict): instantiation parameters

Returns:

obj (MoveGenerator): the created instance

property parameters¶

Get current state and instantiation parameters.

Returns:

parameters (dict): The current state and instantiation parameters dictionary.

update(params)¶

Update instance using parameters

Parameters:

params (dict): instantiation parameters. Can be pure (key,value) dictionary or as returned from parameters instance property

pick_from_list(engine)¶

Randomly picks an atom’s index from atomsList. This method checks and verifies maximumCollected prior to picking and index.

Parameters:

engine (Engine): The engine calling the method.

Returns:

index (None, np.ndarray): Atom index wrapped in a numpy.ndarray. If None is returned than picking is not allowed.

fullrmc.Generators package¶

Walks¶

Translations¶

Rotations¶

Volumes¶

Neighbours¶

Agitations¶

Swap¶

Removes¶

Table of Contents

Previous topic

Next topic

Navigation

fullrmc.Generators package¶

Walks¶

Translations¶

Rotations¶

Volumes¶

Neighbours¶

Agitations¶

Swap¶

Removes¶

Table of Contents

Previous topic

Next topic

Quick search

Navigation