Engine is fullrmc’s main module. It contains ‘Engine’ the main class of fullrmc which is the stochastic artist. The engine main atomic structure input file format is the Protein Data Bank (PDB), ‘.pdb’ . A PDB file is chosen because of its flexible to define atomic and molecular structure. In addition to a PDB file, fullrmc’s engine can also consume .cif and .xyz files to set the initial atomic structure using respectively ‘read_cif_set_pdb’ and ‘read_xyz_set_pdb’ engine methods. Also, one can use ‘build_crystal_set_pdb’ engine method as another method to set the initial pdb structure using a set of crystallographic information. fullrmc’s Engine is built to handle many experimental data while controlling the evolution of the system using user-defined molecular and atomistic constraints such as bond-length, bond-angles, dihedral angles, atomic/molecular-distances, etc.
random() -> x in the interval [0, 1).
Bases: object
This is a versions adapter to insure some backward compatibility of fullrmc’s engines. It’s used to make sure old version engines are loadable in newer versions.
Add repository entries that are missing from an older, already-saved engine or constraint object because they were introduced in a newer fullrmc version. This keeps engines saved with an older fullrmc version loadable in newer versions without losing or breaking their state.
repo (pyrep.Repository): The engine’s repository instance.
frame (string): The frame being loaded.
obj (Engine, Constraint): The engine or constraint instance to check and patch for missing data.
engine (Engine): The engine instance being loaded.
Normalize an older, already-saved engine’s internal repository layout and multiframe structure metadata so it matches what the current fullrmc version expects (e.g. renaming legacy internal attribute names, backfilling the optimizations lookup table, and fixing up multiframe experimental constraints parameters).
repo (pyrep.Repository): The engine’s repository instance.
frame (string): The frame being loaded.
obj (Engine, Constraint): The engine or constraint instance to normalize.
engine (Engine): The engine instance being loaded.
Bases: object
Engine runtime intercept hook. This can be used by a thread or another process to intercept a running stochastic engine to do different actions such as stop, save, export a pdb file or reset the standard error.
Calling InterceptHook methods on a non-running engine will be ignored.
path (string): Engine repository path
password (string): Engine repository password. If None, default value will be given hoping that the running engine repository password is also the default one. Otherwise the hook connection will fail.
From a different python process, run the following code to handle a hook of a running engine.
# import fullrmc's InterceptHook
from fullrmc import InterceptHook
# create hook
hook = InterceptHook(path='my_engine.stc')
# safely force stopping running engine
hook.stop_engine()
# safely force saving running engine
hook.save_engine()
# safely export a pdb file of the current engine structure status
hook.export_pdb()
# safely reset standard error during engine runtime
hook.reset_standard_error()
Stop a running engine
Stop a running builder
Force saving a running engine
Export a pdb of the current state of a running engine
Reset a running engine total standard error
Get engine instance intercept hook
Release all unexecuted hooks from engine
Bases: object
fullrmc’s engine, is used to launch a stochastic modelling which is different from traditional Reverse Monte Carlo (RMC). It has the capability to use and fit simultaneously multiple sets of experimental data. One can also define constraints such as distances, bonds length, angles and many others.
path (None, string): Engine repository (directory) path to save the engine. If None is given path will be set when saving the engine using Engine.save method. If a non-empty directory is found at the given path an error will be raised unless freshStart flag attribute is set to True.
logKwargs (None, dict): Logging kwargs dictionary. This will be used to update Globals.LOGGER using update method
freshStart (boolean): Whether to remove any existing fullrmc engine at the given path if found. If set to False, an error will be raise if a fullrmc engine or a non-empty directory is found at the given path.
timeout (number): The maximum delay or time allowed to successfully set the lock upon reading or writing the engine repository
password (None, string): Engine repository password. If None, default value will be given.
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...
# Re-define moves generators if needed ...
# save engine
ENGINE.save()
# run engine for 10000 steps and save only at the end
ENGINE.run(numberOfSteps=10000, saveFrequency=10000)
Create engine given a snapshot
snapshot (string, list): snapshot file path given as a string or the list of snapshot file lines
enginePath (string): Engine file path to save.
replace (boolean): whether to replace engine if found at given or derived enginePath
engine (fullrmc.Engine.Engine): the built engine instance
# import engine
from fullrmc.Engine import Engine
# build engine from snapshot
ENGINE = Engine.build_engine_from_snapshot(snapshot="my_engine.snapshot", enginePath="my_engine")
Create multiframe with one subframe from given optimization
frame (None, str): the name of the multiframe to add. If engine is empty, frame ‘0’ will be used automatically used
optEngine (fullrmc.Engine): the fullrmc engine containing the optimization
confName (None, str): the optimization configuration name in optimization engine. If None, used optimization will be used or if a single optimization is defined, it will be used automatically
supercell (None, list): The supercell size. If None, optimization supercell will be used
contiguous (bool): whether to create structure from contiguous optimized structure
optimizedStructure (bool): whether to used optimized structure or initially set one
addExperimentalConstraint (bool): whether to add optimization experimental constraints to stochastic engine
addRigidConstraints (bool): whether to add optimization rigid constraints to stochastic engine
**eKwargs: stochastic engine instantiation kwargs
engine (fullrmc.Engine): the same engine instance (self), returned for chaining, now containing the newly created frame
Create a stochastic engine from an optimizer configuration. Optimization structure and constraints will be set to frame ‘0’
path (string): Directory path to save the engine.
optEngine (fullrmc.Engine): the fullrmc engine containing the optimization
confName (None, str): the optimization configuration name in optimization engine. If None, used optimization will be used or if a single optimization is defined, it will be used automatically
supercell (None, list): The supercell size. If None, optimization supercell will be used
contiguous (bool): whether to create structure from contiguous optimized structure
optimizedStructure (bool): whether to used optimized structure or initially set one
addExperimentalConstraint (bool): whether to add optimization experimental constraints to stochastic engine
addRigidConstraints (bool): whether to add optimization rigid constraints to stochastic engine
**eKwargs: stochastic engine instantiation kwargs
engine (fullrmc.Engine): created fullrmc stochastic engine
Create a snapshot of engine that can be used to export engine to fullrmc on the cloud
filePath (str): file path to export blocks to
frames (None, list): list of frames to create the snapshot. If None, all engine frames will be considered
description (None, string, list): description to include in header
replace (boolean): whether to replace existing engine snapshot
ENGINE.create_snapshot(filePath="my_engine.snapshot")
Alias to create_snapshot
Codify engine full state to a code that once executed it will regenerate and save the engine on disk. This is a better alternative to transferring engine from one system to another. The generated code is python 2 and 3 compatible and operating system safe allowing to get an executable code to regenerate the engine.
export (None, str): file to write generated codified engine code. If string is given, it’s the file path
name (str): engine variable name in the generate code
engineSaveName (None,str): directory path to save engine upon executing the codified engine code
frames (None, str, list): the list of frames to codify. At least one traditional frame must be given. If None, all frames will be codified.
addDependencies (bool): whether to add imports dependencies to the generated code header. Dependencies will always be added to the code header in the exported file.
dependencies (list): list of dependencies import strings
code (str): the codified engine code
The engine’s pyrep.Repository instance used for saving and loading. None if the engine has not been saved yet.
The engine repository’s locker instance used for concurrent-access locking. None if the engine has not been saved yet.
Used frame multiframe meta-structure definition.
Engine repository password.
The stochastic engine repository path if set or saved.
The stochastic engine repository directory name.
The stochastic engine version.
The stochastic engine id.
The stochastic engine information (version, id) tuple.
The stochastic engine frames dictionary copy.
The stochastic engine multiframes name.
The stochastic engine traditional frames name.
The stochastic engine list of traditional frames name and multiframes path.
The stochastic engine frame in use.
The stochastic engine last moved group instance index in groups list.
The stochastic engine last moved group instance.
The stochastic engine last moved atoms index.
The stochastic engine state.
Number of generated moves.
Removed atoms tuple (tried, accepted, ratio)
Number of tried moves.
Number of accepted moves.
Number of tolerated steps in spite of increasing totalStandardError
Tolerance in percent.
The stochastic engine defined groups list.
The stochastic engine pdbparser instance.
The structure supercell attribute. If set, it’s a list of unitcells dictionaries where keys are atom ‘indexes’ in the unitcell, unitcell ‘position’ in the supercell and the list of 26 first unitcells ‘neighbours’ for the unitcell.
Atoms chain identifiers list
Sorted set of all existing atom chain identifiers.
Length of atoms chain identifiers set.
Number of atoms per chain identifier dictionary.
Atoms Segments list
Sorted set of all existing atom segments.
Length of atoms segments set.
Number of atoms per segment dictionary.
Atoms Sequences list
Sorted set of all existing atom sequences.
Length of atoms sequences set.
Number of atoms per sequence dictionary.
Atoms residues list
Sorted set of all existing atom residues.
Length of atoms residues set.
Number of atoms per residue dictionary.
Engine’s boundaryConditions instance.
Whether boundaryConditions are periodic.
Whether boundaryConditions are infinte.
The boundary conditions basis vectors in case of PeriodicBoundaries, None in case of InfiniteBoundaries.
Maximum length that the structure can get to before running into periodic boundary conditions atomic images
The boundary conditions reciprocal basis vectors in case of PeriodicBoundaries, None in case of InfiniteBoundaries.
The boundary conditions basis volume in case of PeriodicBoundaries, None in case of InfiniteBoundaries.
The real coordinates of the current configuration.
The box coordinates of the current configuration in case of PeriodicBoundaries. Similar to realCoordinates in case of InfiniteBoundaries.
Number of molecules.
Atoms molecule index numpy array.
Atoms molecule name list.
Atoms element index numpy array indexing elements sorted set.
Sorted set of all existing atom elements.
Atoms element list.
Atoms name index numpy array indexing names sorted set
Sorted set of all existing atom names.
Atoms name list.
Length of atoms name set.
Number of atoms in the pdb.
Number of atoms per name dictionary.
Number of different elements in the pdb.
Number of atoms per element dictionary.
System’s number density computed as \(\rho_{0}=\frac{N}{V}\) where N is the total number of atoms and V the volume of the system.
Copy list of all constraints instances.
Engine’s group selector instance.
Engine’s last recorded totalStandardError of the current configuration.
Engine’s experimental constraints loss function
Timeout to successfully acquire the lock upon reading or writing to the repository
Get molecules dictionary where keys are molecule names and values are dictionaries where keys are molecules index and values are ‘atoms_index’, ‘atoms_name’ and ‘atoms_element’ of the atoms in the molecule.
Get a list of molecules (name,element_composition,occurrence) triplets
Get a list of molecules (name,name_composition,occurrence) triplets
Get a list of molecules (name,element_composition,name_composition,occurrence) quadruplets
Get engine available dft engines
Get engine available optimization structures
Get engine crystal optimizer instance if instanciated
Get fullrmc engine Density-Functional Theory Engine
Get engine crystal optimizer solver instance if instanciated
Start quantum-espresso dft engine
executablesDir (None, string): quantum-espresso executables path. If None, ‘~/quantum_espresso/qe/bin’ will be used
path. If None, ‘~/quantum_espresso/pseudo’ will be used
Set repository access timeout
timeout (number): The maximum delay or time allowed to successfully set the lock upon reading or writing the engine repository
Get multiframe structure metadata
frame (None, string): multiframe of subframe name. If None is given, used frame will be used. An error will be raised if given frame is not a subframe or a multiframe
original (boolean): whether to get metadata of current structure state or original as set
metadata (dict): multiframe original structure metadata dictionary
Get multiframe structure type given a frame.
frame (None, string): multiframe name. If None, used frame will be used. Given frame must be a multiframe or a subframe
pull (boolean): whether to force pulling multiframe structure from repository
structure (dict): multiframe meta-structure dictionary
The structure supercell attribute. Unlike Engine.supercell property, this method is fullrmc version compatible that reconstructs missing unitcell properties.
frame (None, string): multiframe name. If None, used frame will be used. Given frame must be a multiframe or a subframe
pull (boolean): whether to force pulling multiframe structure from repository
supercell (None, dict): supercell structure. If frame structure is not a supercell, None is returned.
Set multiframe structure as statistical, nanoscopic or mesoscopic. If nanoscopic structure is given, frames actual boundary conditions and number density will be updated calling set_boundary_conditions.
When nanoscopic, ‘_shapeFuncParams’ will be automatically adjusted for all relevant constraints in multiframeStructure[‘experimental_constraints’]
N.B. for density reasons, only infinite boundary conditions are allowed for nanoscopic computation. PeriodicBoundaries are implemented but an exception will be raised if set so.
structure (None, dict, string): structure data dictionary. If None, statistical will be set automatically. If string is given, then ‘statistical’ and ‘mesoscopic’ is accepted. Otherwise a dictionary must be given including ‘type’ key along with other needed information
frame (None, string): multiframe to set structure. If None, used frame will be used. Given frame must be a multiframe or a subframe
structure (dict): the multiframe structure
from fullrmc.Globals import WATER_NUMBER_DENSITY
structure = {'type':'nanoscopic', 'boundaryConditions':None,
'numberDensity':WATER_NUMBER_DENSITY,
'grainSize':{None:3, 'h':5},
'subframe_reference':'multi/0'}
ENGINE.set_multiframe_structure(structure=structure, frame='multi')
Set grain size for multiframe structure.
grainSize (number, dict):
frame (None, string): multiframe to set structure. If None, used frame will be used. Given frame must be a multiframe or a subframe
structure (dict): the multiframe structure
Reset multiframe structure. This will simply update constraints parameters across if necessary
frame (None, string): multiframe to set structure. If None, used frame will be used. Given frame must be a multiframe or a subframe
structure (dict): the multiframe structure
Reset multiframe structure by calling Engine.set_multiframe_structure using the given frame structure. This will ensure resetting the multiframe structure metadata as well as all constraints
frame (None, string): multiframe to set structure. If None, used frame will be used. Given frame must be a multiframe or a subframe
structure (dict): the multiframe structure
Get original data as initialized and parsed from pdb.
name (string): Data name.
frame (None, string): get original data of a particular frame. If None, engine used frame will be used
value (object): Data value
Get whether a fullrmc engine is stored in the given path.
path (string): The path to fetch.
repo (boolean): Whether to return repository if an engine is found. Otherwise None is returned.
mes (boolean): Whether to return explanatory message.
safeMode (boolean): whether to acquire the lock upon loading. This is not necessary unless another process is writing to the repository at the same time.
result (boolean): The fetch result, True if engine is found False otherwise.
repo (pyrep.Repository): The repository instance. This is returned only if ‘repo’ argument is set to True.
message (string): The explanatory message. This is returned only if ‘mes’ argument is set to True.
Save engine to disk.
path (None, string): Repository path to save the engine. If path is None, engine’s path will be used. If path and engine’s path are both None, and error will be raised.
copyFrames (boolean): If path is None, this argument is discarded. This argument sets whether to copy all frames data to the new repository path. If path is not None and this argument is False, Only used frame data will be copied and other frames will be discarded in new engine.
N.B. If path is given, it will automatically update engine’s path to point towards given path.
Load and return engine instance. None of the current engine attribute will be updated. Must be used as the following:
# import engine
from fullrmc.Engine import Engine
# load an existing engine
ENGINE = Engine.load(path)
path (string): Directory path to save the engine.
safeMode (boolean): whether to acquire the lock upon loading. This is not necessary unless another process is writing to the repository at the same time.
engine (Engine): Engine instance.
Set the log file basename.
logFile (None, string): Logging file basename. A logging file full name will be the given logFile appended ‘.log’ extension automatically.
Check whether a given frame exists.
frame (string): Frame name.
result (boolean): True if frame exists False otherwise.
Add a one or many (multi)frame to engine. Pdb structure must be set before adding any frame
frames (string, dict, list): It can be a string to add a single frame, a dictionary to add a single multiframe or a list of strings and/or dictionaries to add multiple (multi)frames.
create (boolean): adding a frame to engine doesn’t create the frame data in the stochastic engine repository. Frames data are created once frame is used. Setting create to True, forces creating the repository data by copying used frame ones. If used frame is not a traditional frame, create will get automatically reset to False
Alias to add_frames
Add a one or many subframes to an existing multiframe. If multiframe data are already created, the subframes data will be automatically copied from the last subframe of the multiframe
multiframe (string): multiframe name to add subframes to
subframes (string, int, list): subframe name or number of subframes to add or a list of subframes name
Alias to add_subframes
Reset frame data to initial pdb coordinates.
frame (string): The frame name to set.
Get whether a given frame name is a normal frame or a multiframe or a multiframe subframe. If frame does not exist an error will be raised.
frame (string): Frame name or repository relative path
isNormalFrame (boolean): Whether it’s a normal single frame
isMultiframe (boolean): Whether it’s a multiframe
isSubframe (boolean): Whether it’s a multiframe subframe path
Reload used frame data from repository. This is nothing else but an alias to ‘Engine.set_used_frame’ with frame set to currently used frame and reload flag set to True
Change engine used frame.
frame (string): The frame to switch to and use from now on.
reload (boolean): Whether to reload frame if currently used frame is the same as given frame to load
_updateRepo (boolean): whether to update repository usedFrame value. Meant to be used internally.
Create new frame by duplicating an already existing one. The duplicated frame must be defined and existing on disk. If duplicated frame is a subframe existing on disk is not a requirement.
frame (string): name of the frame that needs to be duplicated
name (string): frame new name to create the duplicate
Clone frame data one to another. The frame cloning data to (cloneTo) will become an exact copy of the frame cloning data from (cloneFrom)
cloneFrom (string): the frame to clone data from
cloneTo (String): the frame to clone data to
Alias to set_used_frame.
Delete frame data from Engine as well as from repository .
frame (string): The frame to delete.
Rename (multi)frame. All frames can be renamed except for frame 0
frame (string): The frame to rename.
newName (string): The new name.
Get a pdb instance of the last refined and save configuration state.
foldIntoBox (boolean): Whether to fold all atoms into PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
contiguous (boolean): Whether to build contiguous molecules using PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, the multiframe structure must be defined as nanoscopic otherwise an error will be raised
split (Boolean): whether to force split multiframe into multiple structures.
pdb (pdbparser, list): The pdb instance of a list pdb instances.
Export a xyz file of the last refined and saved configuration state.
path (None, string): the xyz file path. If None then xyz string format is returned
foldIntoBox (boolean): Whether to fold all atoms into PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
contiguous (boolean): Whether to build contiguous molecules using PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, the multiframe structure must be defined as nanoscopic otherwise an error will be raised
split (Boolean): whether to force split multiframe into multiple structures. This will result in creating a zip file of all of those if path is not None.
content (None, str, list): If path is string then None is returned otherwise the xyz file as a string or a list of those will be returned
Export a cif file of the last refined and saved configuration state.
path (None, string): the cif file path. If None then cif string format is returned
foldIntoBox (boolean): Whether to fold all atoms into PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
contiguous (boolean): Whether to build contiguous molecules using PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, the multiframe structure must be defined as nanoscopic otherwise an error will be raised
split (Boolean): whether to force split multiframe into multiple structures. This will result in creating a zip file of all of those if path is not None.
content (None, str, list): If path is string then None is returned otherwise the cif file as a string or a list of those will be returned
Export a pdb file of the last refined and saved configuration state.
path (None, string): the pdb file path. If None then pdb string format is returned
foldIntoBox (boolean): Whether to fold all atoms into PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
contiguous (boolean): Whether to build contiguous molecules using PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, the multiframe structure must be defined as nanoscopic otherwise an error will be raised
split (Boolean): whether to force split multiframe into multiple structures. This will result in creating a zip file of all of those if path is not None.
content (None, str, list): If path is string then None is returned otherwise the pdb file as a string or a list of those will be returned
Set experimental constraints loss function to use during stochastic engine runtime.
loss (str, dict): the loss function name. Known losses names are
ae: Absolute Error defined as \(\Omega_{i}W_{i}\left|\Delta_{i}\right|\)
se: Squared Error defined as \(\Omega_{i}W_{i}(\Delta_{i})^{2}\)
rae: Relative Absolute Error defined as \(\Omega_{i}W_{i}\frac{\left|\Delta_{i}\right|}{S(1/(10^{-3}+\left|D_{i}\right|))}\)
rse: Relative Squared Error defined as \(\Omega_{i}W_{i}\frac{\Delta_{i}^{2}}{S(1/(10^{-3}+\left|D_{i}\right|))}\)
lae: Log Absolute Error defined as \(\Omega_{i}W_{i}Ln(1+\left|\Delta_{i}\right|)\)
lse: Log Squared Error defined as \(\Omega_{i}W_{i}Ln((1+(\Delta_{i})^{2})\)
peaks: Peaks Biased Error defined as \(\Omega_{i}W_{i} \left( \left|D_{i}\right|-min(\left|D_{i}\right|)+1 \right) \left|\Delta_{i}\right|\)
welsch: function defined as \(\Omega_{i}Ln\left(\frac{1}{2}(\frac{\left|\Delta_{i}\right|}{c})^{2}+1\right)\)
cauchy: function defined as \(\Omega_{i}\left(1-e^{-\frac{1}{2}(\frac{\left|\Delta_{i}\right|}{c})^{2}}\right)\)
adjustable: function defined as \(\Omega_{i}\frac{|\alpha-2|}{\alpha}\left((\frac{(\frac{\left|\Delta_{i}\right|}{c})^{2}}{|\alpha-2|}+1)^{\frac{\alpha}{2}}-1\right)\) Special cases for adaptive loss are when \(\alpha\) is set to 0 ‘adaptive’ loss will be equal to ‘cauchy’; when \(\alpha\) is set to 2 ‘adaptive’ loss will be similar to ‘se’ \(\frac{\left|\alpha-2\right|}{\alpha} \left(\frac{\left|\Delta_{i}\right|}{c} \right)^{2}\); when \(\alpha\) approches \(-\infty\) ‘adaptive’ approaches ‘welsch’
smart-uniformize: this is a machine learning based loss implementation that will optimize the loss function hyper-curvature by attempting to uniformize the absolute relative error probability distribution. Learning will happen every ‘update’ stochastic engine accepted step and by a ‘learning_rate factor up to a ‘clipping’ value. Allowed parameters are ‘learning_rate’, ‘clipping’ and ‘update’
\(E_{i}\): experimental data at point \(i\)
\(M_{i}\): model data at point \(i\)
\(\Delta_{i}=E_{i}-M_{i}\): the difference between the experimental data and model at point \(i\)
\(<E>\): the experimental data mean
\(D_{i}=E_{i}-<E>\): the difference between experimental data at point \(i\) and the global mean
\(S\): sigmoid function defined as \(S(x)=\frac{1}{1+e^{-x}}\)
\(\Omega_{i}\): loss warping added at point \(i\). This is set using the ‘warping’ parameter
\(W_{i}\): error weight at point \(i\). This weight is set using ‘constraint.set_data_weight’ method. By default it’s None
\(Ln\): natural logarithm function
agg (string): set how to aggregate the computed point loss. It can be ‘sum’ for \(\sum \limits_{i}^{N} loss_{i}\) or ‘mean’ for \(\frac{\sum \limits_{i}^{N} loss_{i}}{N}\). Here \(N\) is total number of experimental data point used within the user set limits and \(loss_{i}\) is the computed loss at point ‘\(i\)’
warping (None, boolean, integer, float, dict): Whether to create loss warping to the loss function upon stochastic engine runtime. Warping will help the engine getting out of local minima without jeopardizing the quality of the atomic model.
If False or None is given, no warping will be created.
If True is given, then random warping will be created at an update frequency of 1000 generated step with a maximum intensity of 0.5 standard deviation.
If integer is given, it will be considered the update frequency of random warping.
If float is given, it will be considered the maximum standard deviation intensity of random warping.
If a dict is given, it can contain the following keys ‘type’ for the different types of allowed warping (default ‘random’); ‘update’ for update frequency (default 1000); ‘intensity’ for maximum standard deviation ratio (default 0.5).
frame (None, string): Target frame name. If None, engine used frame is used.
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# Add multiframe 'size_distribution' ...
# Set loss function for frame 0
ENGINE.set_loss_function(loss={'name':'adjustable', 'alpha':0.5, 'c':1}, frame='0')
# Set loss function for all multiframe 'size_distribution' subframes
ENGINE.set_loss_function(loss='welsch', agg='sum', warping={'type':'random', 'update':100, 'intensity':0.5}, frame='size_distribution')
Resets loss function runtime data
frame (None, string): Target frame name. If None, engine used frame is used.
Set engine’s runtime tolerance value.
tolerance (number): The runtime tolerance parameters. It’s the percentage [0,100] of allowed unsatisfactory ‘tried’ moves.
frame (None, string): Target frame name. If None, engine used frame is used.
Set engine’s group selector instance.
selector (None, GroupSelector): The GroupSelector instance. If None is given, RandomSelector is set automatically.
frame (None, string): Target frame name. If None, engine used frame is used.
This will save groups to repository. Must be called after altering groups properties such as setting a new move generator.
Clear all engine’s defined groups.
Remove groups by instance, name or index
groups (integer, string, Group, list): groups to remove, this can be a specific group index, or a group name or a group instance or a list of all of those
Add a group to engine’s groups list.
g (Group, integer, list, set, tuple numpy.ndarray): Group instance, integer, list, tuple, set or numpy.ndarray of atoms index.
name (None, string): group name. If g is a Group instance, Group.set_name will be called if given name is not None. If g is not a Group instance and name is None it will automatically changed to ‘group’.
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups if given as indexes will set as subset groups otherwise groups given as groups instances won’t be touched
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
_check (boolean): meant to be used internally
Set engine’s groups.
groups (None, Group, list): A single Group instance or a list, tuple, set of any of Group instance, integer, list, set, tuple or numpy.ndarray of atoms index that will be set one by one by set_group method. If None is given, single atom groups of all atoms will be all automatically created which is the same as using set_groups_as_atoms method.
name (None, string, list): groups name. If string is given, the same name will be given to all groups. If list is given, it must have the same length as the number of given groups
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups if given as indexes will set as subset groups otherwise groups given as groups instances won’t be touched
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
add (boolean): whether to add newly generated groups to old ones
_check (boolean): meant to be used internally
Build groups given a list of groupBy keywords and a filter expression
filter (None, string): filter expression string that will be evaluated to select the atoms to consider while building the groups. Expression can ingest all python math mathematical functions and constants along with all of engine atoms ‘index’, ‘residue’,’sequence’, ‘segment’,’chainIdentifier’,’element’, ‘name’, ‘x’, ‘y’, ‘z’, ‘moleculeIndex’, ‘moleculeName’ attributes. If None is given, all atoms are considered.
groupBy (None, string, list): List of group by keywords to create atoms grouping. If None is given, all remaining atoms after filtering will be used to create a single group. If a string or a list of strings is given, it must include any of the following pdb property keywords [‘index’,’residue’,’sequence’,’segment’, ‘chainIdentifier’,’element’,’name’, ‘moleculeIndex’, ‘moleculeName’] that will be used to group remaining atoms after filtering into separate groups of similar groupBy properties. ‘index’ groupBy keyword take over all other keywords as it forces groups to be of single atom corresponding to the atom index. groupBy=[‘residue’,’sequence’,’segment’] is the groupBy list used by default in fullrmc to identify molecules in a pdb structure. Just like filters, groupBy keywords are not case sensitive.
name (None, string): built groups name. If None is given, name will be built automatically per group
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups if given as indexes will set as subset groups otherwise groups given as groups instances won’t be touched
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
add (boolean): whether to add newly generated groups to old ones
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# build a single group of ti atoms confined (y,z) slice where x is between -1 and 1 angstrom
# notice that setting to False will result in removing existing groups from stochastic engine
# and set the newly created group
ENGINE.build_groups( groupBy=None, filter="element == 'ti' and -1<=x<=1", add=False )
Build groups of molecules and molecules’ subset given a list of definitions
definitions (list, tuple, string, integer): list of molecular definitions. List items can be list, tuple, string or an integer.
If string, this must be the molecule name and groups of molecules will be created.
If integer, it will be the molecule index to create a group of
If list or tuple, at least two items are required. The first item can be a molecule name, index or a list of molecule indexes. The remaining items can be any combination of string referencing atom name or element, integer referencing atom index in the molecule or a tuple of two items where the first item can be ‘name’ or ‘element’ and the second item is the atom name or element
name (None, string): built groups name. If None is given, name will be built automatically per group
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups if given as indexes will set as subset groups otherwise groups given as groups instances won’t be touched
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
add (boolean): whether to add newly generated groups to old ones
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# set molecular groups
ENGINE.set_molecular_groups( definitions=[('THF', 'C1', 'H11', 'H12'), # grouping atoms by name or element 'C1','H11','H12' of all 'THF' molecules individually
('THF', 'O'), # grouping atoms by name or element 'O' of all 'THF' molecules individually
10,0,1, # grouping all atoms of molecules index 10,0,1 individually
'THF', # grouping all atoms of all 'THF' molecules individually
([0,1,100], 1,'C',10), # group atom index 1 and 10 and atoms name or element 'C' of molecules index 0,1 100 individually
([0,1,100], 1,('name','C1'),('element','O'),10),# group atom index 1 and 10 and atoms name 'C1' and atoms element 'O' of molecules index 0,1 100 individually
] )
Construct groups as found in parallel planes given a plane vectors, width and an origin to start creating the planes
plane (string, list): the plane vectors representation
width (number): the width of the planes
origin (list): the origin that will be used as reference to start slicing the space into planes
splits (None, list): list of splitting expression that can be used to split every generated plane into multiple subsets of the group prior to combining and creating the groups
combine (None, integer, list, tuple): Whether to combine created planes to form groups of multiple planes. If Integer, it must be the number of planes to combine together. If list, it must be a list of lists where each list will have the indexes of planes to combine to form groups. If tuple, it must contain 2 items, the first item must be the first group index and the second one the number of planes to start combining starting from the given first group index.
completeMolecules (boolean): whether to complete molecule’s atoms when any atom of a molecule is found in a plane
original (boolean): whether to consider the original structure atoms coordinate or the ones of the current engine state
foldIntoBox (bool): whether to fold atoms into boundary conditions box before building planes
filter (None, string): filter expression string that will be evaluated to select the atoms to consider while building the planes. Expression can ingest all python math mathematical functions and constants along with all of engine atoms ‘index’, ‘residue’,’sequence’, ‘segment’,’chainIdentifier’,’element’, ‘name’, ‘x’, ‘y’, ‘z’ attributes. If None is given, all atoms are considered.
name (None, string): built groups name. If None is given, name will be built automatically per group
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups will be converted to subset groups before setting to engine
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
add (boolean): whether to add newly generated groups to old ones
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# use a string plane
ENGINE.set_groups_as_planes(plane='xy', filter="element =='Ba'", add=False )
# split planes into 2
ENGINE.set_groups_as_planes(plane='xy', filter="element =='Ba'", splits=["name == 'Ba1'", "name != 'Ba2'"] )
# add another set of plane groups
ENGINE.set_groups_as_planes(plane=[[1,0,0],[1,-1,3]], add=True )
# add another set of plane groups combined in pairs
ENGINE.set_groups_as_planes(plane=[[1,0,0],[1,-1,3]], combine=2, add=True )
Construct groups as found in parallel rods (square cylinders) given a vector director and an origin to start creating the rods
vector (string, list): the vector representation
width (number): the width of the planes
origin (list): the origin that will be used as reference to start slicing the space into planes
original (boolean): whether to consider the original structure atoms coordinate or the ones of the current engine state
splits (None, list): list of splitting expression that can be used to split every generated rod into multiple subsets of the group prior to combining and creating the groups
combine (None, integer, list, tuple): Whether to combine created rods to form groups of multiple rods. If Integer, it must be the number of rods to combine together. If list, it must be a list of lists where each list will have the indexes of rods to combine to form groups. If tuple, it must contain 2 items, the first item must be the first group index and the second one the number of rods to start combining starting from the given first group index.
completeMolecules (boolean): whether to complete molecule’s atoms when any atom of a molecule is found in a rod
foldIntoBox (bool): whether to fold atoms into boundary conditions box before building rods
filter (None, string): filter expression string that will be evaluated to select the atoms to consider while building the planes. Expression can ingest all python math mathematical functions and constants along with all of engine atoms ‘index’, ‘residue’,’sequence’, ‘segment’,’chainIdentifier’,’element’, ‘name’, ‘x’, ‘y’, ‘z’ attributes. If None is given, all atoms are considered.
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups will be converted to subset groups before setting to engine
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
name (None, string): built groups name. If None is given, name will be built automatically per group
add (boolean): whether to add newly generated groups to old ones
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# use a string plane
ENGINE.set_groups_as_rods(vector='xy', filter="element =='Ba'", add=False )
# split rods into 2
ENGINE.set_groups_as_rods(vector='xy', filter="element =='Ba'", splits=["name == 'Ba1'", "name != 'Ba2'"] )
# add another set of plane groups
ENGINE.set_groups_as_rods(vector=[[1,0,0],[1,-1,3]], add=True )
Construct groups as found in parallel supercell rods of atom indexes
vector (string, list): the vector representation
filter (None, string): filter expression string that will be evaluated to select the atoms to consider while building the planes. Expression can ingest all python math mathematical functions and constants along with all of engine atoms ‘index’, ‘residue’,’sequence’, ‘segment’,’chainIdentifier’,’element’, ‘name’, ‘x’, ‘y’, ‘z’ attributes. If None is given, all atoms are considered.
splits (None, list): list of splitting expression that can be used to split every generated rod into multiple subsets of the group prior to combining and creating the groups
combine (None, integer, list, tuple): Whether to combine created rods to form groups of multiple rods. If Integer, it must be the number of rods to combine together. If list, it must be a list of lists where each list will have the indexes of rods to combine to form groups. If tuple, it must contain 2 items, the first item must be the first group index and the second one the number of rods to start combining starting from the given first group index.
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups will be converted to subset groups before setting to engine
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
name (None, string): built groups name. If None is given, name will be built automatically per group
add (boolean): whether to add newly generated groups to old ones
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# use a string plane
ENGINE.set_supercell_groups_as_rods(vector='xy', filter="element =='Ba'", add=False )
# split rods into 2
ENGINE.set_supercell_groups_as_rods(vector='xy', filter="element =='Ba'", splits=["name == 'Ba1'", "name != 'Ba2'"] )
# add another set of plane groups
ENGINE.set_supercell_groups_as_rods(vector=[[1,0,0],[1,-1,3]], add=True )
Construct groups as found in parallel supercell planes of atom indexes
plane (string, list): the plane vectors representation
filter (None, string): filter expression string that will be evaluated to select the atoms to consider while building the planes. Expression can ingest all python math mathematical functions and constants along with all of engine atoms ‘index’, ‘residue’,’sequence’, ‘segment’,’chainIdentifier’,’element’, ‘name’, ‘x’, ‘y’, ‘z’ attributes. If None is given, all atoms are considered.
splits (None, list): list of splitting expression that can be used to split every generated plane into multiple subsets of the group prior to combining and creating the groups
combine (None, integer, list, tuple): Whether to combine created planes to form groups of multiple planes. If Integer, it must be the number of planes to combine together. If list, it must be a list of lists where each list will have the indexes of planes to combine to form groups. If tuple, it must contain 2 items, the first item must be the first group index and the second one the number of planes to start combining starting from the given first group index.
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups will be converted to subset groups before setting to engine
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
name (None, string): built groups name. If None is given, name will be built automatically per group
add (boolean): whether to add newly generated groups to old ones
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# Add constraints ...
# use a string plane
ENGINE.set_supercell_groups_as_planes(plane='xy', filter="element =='Ba'", add=False )
# split planes into 2
ENGINE.set_supercell_groups_as_planes(plane='xy', filter="element =='Ba'", splits=["name == 'Ba1'", "name != 'Ba2'"] )
# add another set of plane groups
ENGINE.set_supercell_groups_as_planes(plane=[[1,0,0],[1,-1,3]], add=True )
Helper method to create groups as single atom group for all atoms. If add is True, created groups will be added to engine existing ones otherwise old groups will be removed.
name (string, list): groups name. If string is given, the same name will be given to all groups. If list is given, it must have the same length as the number of molecules in the system
add (boolean): whether to add newly generated groups to old ones
Helper method to automatically to create molecular groups of atom indexes according to molecules indexes. If add is True, created groups will be added to engine existing ones otherwise old groups will be removed.
When parsing the pdb structure file, fullrmc considers a molecule as the consecutive collection of atoms sharing the same ‘Residue name’, ‘Sequence number’ and ‘Segment identifier’.
name (string, list): groups name. If string is given, the same name will be given to all groups. If list is given, it must have the same length as the number of molecules in the system
subsettingSize (None, int,float,tuple): If None, no subsetting will be created. If given, all groups will be converted to subset groups before setting to engine
subsettingType (string): it can be ‘random’ for RandomSubsetGroup or ‘centered’ for CenteredSubsetGroup
add (boolean): whether to add newly generated groups to old ones
Create groups as unitcells. If supercell is not defined, an error will be raised. Otherwise, this is simply an alias to set_groups_as_molecules
Using pdbparser.Utilities.Crystallography.CrystalMaker, create a supercell and set pdb structure
maker (pdbparser.Utilities.Crystallography.CrystalMaker): maker instance
supercell (None, tuple): supercell dimension to create. If None then a supercell of the size of the unit cell will be created.
Build crystal using symmetry operations, atoms coordinates and occupancy and unitcell boundary conditions
symOps (list): list of symmetry operations
atoms (atoms): list of tuples where every tuple contains the atom element name, x,y,z coordinates and an optional occupancy. If an atom occupancy is missing, it’s then considered to be 1
unitcellBC (list, numpy.ndarray, pdbparser.Utilities.BoundaryConditions.PeriodicBoundaries): unitcell boundary conditions instance or parameters defining the unitcell size and shape. When a list of parameters is given, it can be a list of the 6 crystallographic lattice parameters (a,b,c,alpha,beta,gamma) or a list of the three boundary condition vectors for (X,Y,Z). If numpy.ndarray is given, it must be an array matrix of shape (3,3) defining the three boundary condition vectors (X,Y,Z) of the boundary conditions.
supercell (None, tuple): supercell dimension to create. If None then a supercell of the size of the unit cell will be created.
maker (pdbparser.Utilities.Crystallography.CrystalMaker): the crystal maker instance
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# build a supercell crystal structure and set it as the engine's structure
symOps = ['X,Y,Z', '-X,Y,-Z', '-X,-Y,-Z', 'X,-Y,Z',
'1/2+X,1/2+Y,Z', '1/2-X,1/2+Y,-Z', '1/2-X,1/2-Y,-Z',
'1/2+X,1/2-Y,Z']
atoms = [('Co',0,0,0,1),('O',0,0.5,1),]
a = 5.18
b = 3.015
c = 3.017
alpha = 90. # (alpha, the angle between b and c)
beta = 125.55 # (beta, the angle between a and c)
gamma = 90. # (gamma, the angle between a and b)
ENGINE.build_crystal_set_pdb(symOps = symOps,
atoms = atoms,
unitcellBC = [a,b,c,alpha,beta,gamma],
supercell = (20,20,20))
# Add constraints ...
# Re-define groups if needed ...
# Re-define groups selector if needed ...
# Re-define moves generators if needed ...
# save engine
ENGINE.save()
# run engine for 10000 steps and save only at the end
ENGINE.run(numberOfSteps=10000, saveFrequency=10000)
Set pdb structure using a .cif file. Cif files come in different flavors and they are hardly standardized.
cif (string, pathlike): cif file path. fullrmc looks for the following information in a cif:
cell information as a space separated 2 columns lines (e.g. _cell_length_a 13.5049(4)) ‘_cell_length_a’, ‘_cell_length_b’, ‘_cell_length_c’, ‘_cell_angle_alpha’, ‘_cell_angle_beta’, ‘_cell_angle_gamma’
loop block containing atoms site factional position with all of ‘_atom_site_fract_x’, ‘_atom_site_fract_y’, ‘_atom_site_fract_z’ and either ‘_atom_site_type_symbol’ or ‘_atom_site_label’
loop block containing symmetry operations with either ‘_space_group_symop_operation_xyz’ or ‘_symmetry_equiv_pos_as_xyz’ If neither are defined, ‘_space_group_name_H-M_alt’ attribute is looked for to map Hermann-Mauguin symbol to Hall symbol and then generating symmetry operations from HALL_TO_SYM_OPS
supercell (None, tuple): supercell dimension to create. If None then a supercell of the size of the unit cell will be created.
_cell_length_a 12.046(3)
_cell_length_b 8.147(1)
_cell_length_c 7.548(2)
_cell_angle_alpha 90
_cell_angle_beta 121.83(2)
_cell_angle_gamma 90
loop_
_symmetry_equiv_pos_as_xyz
x,y,z
-x,y,1/2-z
-x,-y,-z
x,-y,1/2+z
1/2+x,1/2+y,z
1/2-x,1/2+y,1/2-z
1/2-x,1/2-y,-z
1/2+x,1/2-y,1/2+z
loop_
_atom_site_label
_atom_site_type_symbol
_atom_site_symmetry_multiplicity
_atom_site_Wyckoff_symbol
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
_atom_site_occupancy
_atom_site_attached_hydrogens
_atom_site_calc_flag
V1 V4+ 4 e 0. 0.7556(3) 0.25 1. 0 d
P1 P1+ 8 f 0.2271(2) 0.6658(3) 0.7122(4) 1. 0 d
O1 O2- 8 f 0.1437(3) 0.7861(4) 0.5472(5) 1. 0 d
O2 O2- 8 f 0.1274(3) 0.7922(4) 0.1589(5) 1. 0 d
O3 O2- 4 e 0. 0.0337(5) 0.25 1. 2 d
O4 O2- 4 e 0. 0.5653(7) 0.25 1. 0 d
cif (string, list): the cif file path or a list of cif file string lines.
supercell (None, tuple): supercell dimension to create. If None then a supercell of the size of the unit cell will be created.
maker (pdbparser.Utilities.Crystallography.CrystalMaker): the crystal maker instance
Set pdb structure using a XYZ chemical file format. Unlike a pdb file, xyz has no molecular information and therefore molecules will not be automatically parsed using a xyz file. All atoms are considered non-bonded.
There is no formal standard format for xyz file. fullrmc adopts the typical format where the atomic system geometry is specified by giving the number of atoms on the first line and a single comment on the second line. Atomic coordinates data start from the third line. Atomic lines are empty space separated and each atomic line must include exactly 4 columns for respectively the atomic element, x, y and z coordinates in the cartesian coordinates system.
In addition, fullrmc allows adding comment lines using ‘#’ at the beginning of a comment line.
Boundary conditions comments are allowed and those must be used as in the following example (# Boundary Conditions: 45.75 0.0 0.0 0.0 45.75 0.0 0.0 0.0 45.75)
# Boundary Conditions: 45.75 0.0 0.0 0.0 45.75 0.0 0.0 0.0 45.75
6750
shape memory NiTi alloy
Ni 35.884 30.895 49.120
Ti 36.177 29.853 50.124
Ni 37.296 30.296 51.074
Ti 38.553 30.400 50.259
Ni 38.357 31.290 49.044
Ti 39.559 31.209 48.082
Ni 34.968 30.340 48.234
Ti 34.923 29.775 50.910
Ni 37.441 29.265 52.113
Ti 39.572 30.954 51.086
Ni 37.155 30.858 48.364
Ti 39.261 32.018 46.920
.
.
.
xyz (string, list): the xyz file path or a list of xyz file string lines.
boundaryConditions (None, InfiniteBoundaries, PeriodicBoundaries, numpy.ndarray, number): The configuration’s boundary conditions. If None, boundaryConditions will be parsed from pdb if existing otherwise, InfiniteBoundaries with no periodic boundaries will be set. If numpy.ndarray is given, it must be pass-able to a PeriodicBoundaries instance. Normally any real numpy.ndarray of shape (1,), (3,1), (9,1), (3,3) is allowed. If number is given, it’s like a numpy.ndarray of shape (1,), it is assumed as a cubic box of box length equal to number.
names (None, list): Atoms names list. If None is given, names will be the same the atom element.
elements (None, list): Atoms elements list. If None is given, elements will be calculated set by parsing the xyz file
moleculesIndex (None, list, numpy.ndarray): Molecules index list. Must have the length of number of atoms. If None is given, moleculesIndex will be set automatically to the number of atoms in the system
moleculesName (None, list): Molecules name list. Must have the length of the number of atoms. If None is given, it is automatically set to ‘XYZ’
Compute and set structure’s supercell attributes. This assumes that the current pdb structure is crystal (like) where atoms in unitcells are created as separate molecules in the pdb. The same sequence of unique atom names are expected in all unitcells. Occupancy and voids are accounted for as long as the sequence of atom names is respected.
size (None, list,tuple,numpy.ndarray): The structure supercell dimension as (i,j,k) where i is the number of unitcells along x axis, j is the number of unitcells along y axis and k the number of unitcells along z axis. If None is given, supercell structure properties will be removed.
Set used frame pdb configuration. Engine and constraints data will be automatically reset but not constraints definitions. If pdb was already set and this is a resetting to a different atomic configuration, with different elements or atomic order, or different size and number of atoms, constraints definitions must be reset manually. In general, their is no point in changing the atomic configuration of a completely different atomic nature. It is advisable to create a new engine from scratch or redefining all constraints definitions.
REMARK this file is generated using 'pdbparser' package
REMARK Boundary Conditions: 30.0 0.0 0.0 0.0 30.0 0.0 0.0 0.0 30.0
ATOM 1 Co01 UNK 1 14.620 16.640 14.930 1.00 0.00 Co
ATOM 2 Co02 UNK 1 14.060 14.080 16.150 1.00 0.00 Co
ATOM 3 Co03 UNK 1 16.580 14.800 15.380 1.00 0.00 Co
ATOM 4 Co04 UNK 1 14.540 14.340 13.500 1.00 0.00 Co
ATOM 5 O001 UNK 1 13.440 15.180 14.760 1.00 0.00 O
.
.
.
pdb (pdbparser, string, list): the configuration pdb as a pdbparser instance or a path string to a pdb file or a list of pdb lines.
boundaryConditions (None, InfiniteBoundaries, PeriodicBoundaries, numpy.ndarray, number): The configuration’s boundary conditions. If None, boundaryConditions will be parsed from pdb if existing otherwise, InfiniteBoundaries with no periodic boundaries will be set. If numpy.ndarray is given, it must be pass-able to a PeriodicBoundaries instance. Normally any real numpy.ndarray of shape (1,), (3,1), (9,1), (3,3) is allowed. If number is given, it’s like a numpy.ndarray of shape (1,), it is assumed as a cubic box of box length equal to number.
names (None, list): Atoms names list. If None is given, names will be automatically extracted by parsing pdb instance.
elements (None, list): Atoms elements list. If None is given, elements will be automatically extracted by parsing pdb instance.
moleculesIndex (None, list, numpy.ndarray): Molecules index list. Must have the length of number of atoms. If None is given, moleculesIndex will be set automatically set by parsing pdb instance.
moleculesName (None, list): Molecules name list. Must have the length of the number of atoms. If None is given, it is automatically generated using the pdb residues name. Molecules name are very important to be unique per type of molecule because this is the only differentiating factor when setting definitions by molecule.
_supercell: For internal use only
Sets the configuration’s boundary conditions. Any type of periodic or infinite boundary conditions is allowed and not restricted to cubic. Engine and constraints data will be automatically reset. Number density will be automatically calculated upon setting boundary conditions. In the case where inifinite boundaries are set, which is needed to simulate isolated atomic systems such as nano-particles, the volume is theoretically infinite and therefore number density must be 0. But experimentally the measured samples are diluted in solvants and the actual number density must be the experimental one. To avoid numerical instabilities, number density will be automatically set to water’s one equal to 0.0333679 and volume will be adjusted to the ratio of number of atoms devided to the given water number density. If this number is not accurate, user can always set the appropriate number density using the stochastic engine ‘set_number_density’ method
boundaryConditions (None, InfiniteBoundaries, PeriodicBoundaries, numpy.ndarray, number): The configuration’s boundary conditions. If None, InfiniteBoundaries with no periodic boundaries will be set. If numpy.ndarray is given, it must be pass-able to a PeriodicBoundaries instance. Normally any real numpy.ndarray of shape (1,), (3,1), (9,1), (3,3) is allowed. If number is given, it’s like a numpy.ndarray of shape (1,), it is assumed as a cubic box of box length equal to number.
frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes boundary conditions will be changed
autoAdjust (bool): automatically adjust certain engine and constraints properties that should be changed along with boundaryConditions (e.g. PairDistributionConstraint.set_shape_function_parameters)
_nAtoms: for internal use only
_broadcast (boolean): for internal use only
Sets system’s number density. This is used to correct system’s volume. It can only be used with InfiniteBoundaries.
numberDensity (number): Number density value that should be bigger than zero.
frame (None, string): Target frame name. If None, engine used frame is used. If multiframe is given, all subframes boundary conditions will be changed
_nAtoms: for internal use only
Set frame real coordinates. Meant for internal use only.
coordinates (numpy.ndarray):coordinates array
frame (None, string): frame name or None to update usedFrame
_broadcast (boolean): for internal use only
Check whether engine molecules are inconsistent or not
result (bool): True if any inconsistencies are found, False otherwise
Automatically fix molecules atomic inconsistencies in the frame
Rename molecules given look up table
molecules (dict): dictionary of old to new molecules name
force (bool): whether to force changing molecule name to molecules name that already exist in the system
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# re-defined molecules for a an atomic system
molecules = {'MOL':'THF', 'RMC':'CH4'}
ENGINE.rename_molecules(molecules)
Rename atoms in a molecule.
molecules (dict): dictionary of molecules name where values are dictionaries or a list of (name/index, new name) pairs
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# re-defined molecules for a an atomic system
molecules = {'MOL':{'O':'O1', 1:'Ti'}, 'THF':[('H11','H_1'),(2,'O')]}
ENGINE.rename_molecule_atoms(molecules)
Define molecules using a lookup table of molecules name and list of atoms index. Each atom in the system must be defined in one single molecule. This method can be called when used frame is a subframe or when only a single traditional frame is defined which is the default frame ‘0’.
molecules (dict): dictionary of molecules name. Values are a list of atom indexes or a list of lists of atom indexes. If a molecule value is a list then all atoms of that list will belong to the same molecule. When value is a list of lists, then atoms will be split into multiple molecules. Molecules sharing the same name will be tested for consistency in terms of atom names and elements order.
# import engine
from fullrmc.Engine import Engine
# create engine
ENGINE = Engine(path='my_engine.stc')
# set pdb file
ENGINE.set_pdb(pdbFileName)
# re-defined molecules for a an atomic system
molecules = {}
for idx,el in enumerate(ENGINE.allElements):
molecules.setdefault('MOL_%s'%el,[]).append(idx)
ENGINE.define_molecules(molecules)
Set moleculesIndex list, assigning each atom to a molecule.
moleculesIndex (None, list, numpy.ndarray): Molecules index list. Must have the length of the number of atoms. If None is given, moleculesIndex will be calculated automatically by parsing pdb and grouping atoms by unique sets of (residue,sequence,segment).
moleculesName (None, list): Molecules name list. Must have the length of the number of atoms. If None is given, it will be automatically generated as the pdb residues name.
_checkForInconsistencies (boolean): for internal use only
_reinitting (boolean): for internal use only
_broadcast (boolean): for internal use only
Set elements and elementsIndex lists, assigning a type element to each atom.
elements (None, list): Elements list, it must have the length of the number of atoms. If None is given, elements will be calculated automatically by parsing pdb instance.
_broadcast (boolean): for internal use only
Set names and namesIndex list, assigning a name to each atom.
names (None, list): The names list. If None is given, names will be generated automatically by parsing pdbparser instance.
_broadcast (boolean): for internal use only
Visualize the last configuration using pdbparser visualize_vmd method.
frame (None, string): The frame to visualize. If None, used frame will be visualized. If given, frame must be created in repostory.
commands (None, list, tuple): List of commands to pass upon calling vmd.
foldIntoBox (boolean): Whether to fold all atoms into PeriodicBoundaries box before visualization. If boundary conditions are InfiniteBoundaries then nothing will be done.
contiguous (boolean): Whether to build contiguous molecules using PeriodicBoundaries box. If boundary conditions are InfiniteBoundaries then nothing will be done.
boxToCenter (boolean): Translate box center to atom coordinates center.
boxWidth (number): Visualize the simulation box by giving the lines width. If 0 or boundary conditions are InfiniteBoundaries then nothing is visualized.
boxStyle (str): The box line style, it can be either solid or dashed. If boundary conditions are InfiniteBoundaries then nothing will be done.
boxColor (str): Choose the simulation box color. If boundary conditions are InfiniteBoundaries then nothing will be done. Available colors are:
blue, red, gray, orange, yellow, tan, silver, green, white, pink, cyan, purple, lime, mauve, ochre, iceblue, black, yellow2, yellow3, green2, green3, cyan2, cyan3, blue2, blue3, violet, violet2, magenta, magenta2, red2, red3, orange2, orange3.
bgColor (str): Set visualization background color.
displayParams(None, dict): Set display parameters. If None is given, default parameters will be applied. If dictionary is given, the following keys can be used.
‘depth cueing’ (default True): Set the depth cueing flag.
‘cue density’ (default 0.1): Set the depth density.
‘cue mode’ (default ‘Exp’): Set the depth mode among ‘linear’, ‘Exp’ and ‘Exp2’.
representationParams(str): Set representation method among the following:
Lines, Bonds, DynamicBonds, HBonds, Points, VDW, CPK, Licorice, Beads, Dotted, Solvent.
Add parameters accordingly if needed like the following.
Points representation accept only size parameter e.g. ‘Points 5’
CPK representation can accept respectively 4 parameters as the following ‘Sphere Scale’, ‘Bond Radius’, ‘Sphere Resolution’, ‘Bond Resolution’ e.g. ‘CPK 1.0 0.2 50 50’
VDW representation can accept respectively 2 parameters as the following ‘Sphere Scale’, ‘Sphere Resolution’ e.g. ‘VDW 0.7 100’
otherParams(None, list, set, tuple): Any other parameters in a form of a list of strings.
e.g. [‘display resize 700 700’, ‘rotate x to 45’, ‘scale to 0.02’, ‘axes location off’]
Add constraints to the engine. If used frame is a normal frame, all other normal frames will have the constraints added. If used frame is a subframe, all other subframes of the same multiframe will have the experimental constraints added to. But given non-experimental constraints will be only added to the used frame.
constraints (Constraint, list, set, tuple): A constraint instance or list of constraints instances
allSubframes (boolean): Whether to also add non-experimental constraints to all other multiframe subframes in case engine used frame is a multiframe subframe.
Remove constraints from engine list of constraints.
constraints (Constraint, list, set, tuple): A constraint instance or list of constraints instances.
allSubframes (boolean): Whether to also remove non-experimental constraints from all other multiframe subframes in case engine used frame is a multiframe subframe.
Reset used frame constraints flags.
used (boolean): whether to reset used constraints only
Re-initialize engine and resets constraints flags and data.
Engine total standard error is computed as the sum of all used experimental constraints’ standard error divided by the variance.
This method will automatically update each constraint variance to normalize constraints contribution to the engine’s total standard error as the follows.
Where:
\(N\) is the number of experimental constraint data point within the used limits.
\(M\) is the number of used experimental constraints.
\(y_{i}\) is the constraint i^{th} experimental data within the used limits.
\(min \left[ \sum \limits_{j}^{M} \left|y_{j}\right| \right]\) is the minimum of all experimental constraints absolute sum of values.
used (boolean): whether to only update used experimental constraints variance
Engine total standard error is computed as the sum of all used experimental constraints’ standard error divided by the variance.
This method will automatically reset each constraint variance to the following
Where:
\(N\) is the number of experimental constraint data point within the used limits.
\(y_{i}\) is the constraint \(i^{th}\) experimental data within the used limits.
\(\bar{y}\) is the average of the constraint’s experimental data value within the used limits.
used (boolean): whether to only update used experimental constraints variance
Engine total standard error is computed as the sum of all used experimental constraints’ standard error divided by the variance.
This method will automatically reset each constraint variance to 1
used (boolean): whether to only update used experimental constraints variance
Compute the total standard error as the sum of all used experimental constraints’ standard error.
Where:
\(variance_{i}\) is the variance value of the constraint i.
\(totStdError\) the engine total standard error \(stdErr_{i}\) the standard error of the constraint i defined as \(\sum \limits_{j}^{points} (target_{i,j}-computed_{i,j})^{2} = (Y_{i,j}-F(X_{i,j}))^{2}\)
constraints (list): All constraints used to calculate total totalStandardError.
current (str): which standard error to use. Can be anything like standardError, afterMoveStandardError or amputatedStandardError, etc.
totalStandardError (float): The computed total standard error.
Compute and set engine’s total totalStandardError of used constraints.
Fetches all engine’s constraints and returns different lists of constraints.
used (boolean): whether to initialize used constraints only. If True, returned lists will contain only used constraints
sortConstraints (boolean): Whether to sort used constraints according to their computation cost property. This can minimize computations and enhance performance by computing less costly constraints first.
usedConstraints (list): All types of active constraints instances that are used at engine’s runtime.
stdConstraints (list): All active constraints instance among usedConstraints list that will contribute to engine’s totalStandardError.
rigidConstraints (list): All active RigidConstraint constraints instance among usedConstraints list that won’t contribute engine’s totalStandardError.
Calls get_constraints method, re-initializes constraints when needed and return them all.
used (boolean): whether to initialize used constraints only. If True, returned lists will contain used constraints only.
force (boolean): Whether to force initializing constraints regardless of their state.
resetLoss (boolean): Whether to reset loss function prior to starting the engine. This will only take effect if chosen loss is not static but machine learning enabled.
sortConstraints (boolean): Whether to sort used constraints according to their computation cost property. This can minimize computations and enhance performance by computing less costly constraints first.
usedConstraints (list): All types of active constraints instances that are used at engine’s runtime.
stdConstraints (list): All active constraints instance among usedConstraints list that will contribute to engine’s totalStandardError.
rigidConstraints (list): All active RigidConstraint constraints instance among usedConstraints list that won’t contribute engine’s totalStandardError.
Run stochastic fitting engine.
numberOfSteps (integer): The number of steps to run.
frame (None, frame): The frame to use to run the engine. If None is given, engine usedFrame will be used
resetLoss (boolean): Whether to reset loss function prior to starting the engine. This will only take effect if chosen loss is not static but machine learning enabled.
updateLoss(boolean): Whether to train loss function during stochastic engine runtime. This will only take effect if chosen loss is not static but machine learning enabled.
sortConstraints (boolean): Whether to sort used constraints according to their computation cost property. This can minimize computations and enhance performance by computing less costly constraints first.
optimize (boolean): Whether to optimize parameters during stochastic engine runtime. Optimization parameters are defined separately in the engine constraints
saveFrequency (integer): Save engine every saveFrequency steps. Save will be omitted if no moves are accepted.
xyzFrequency (None, integer): Save coordinates to .xyz file every xyzFrequency steps regardless if totalStandardError has decreased or not. If None is given, no .xyz file will be generated.
restartPdb (None, string): Export a pdb file of the last configuration at the end of the run. If None is given, no pdb file will be exported. If string is given, it should be the full path of the pdb file.
xyzPath (string): Save coordinates to .xyz file.
ncores (None, integer): set the number of cores to use. If None is given, ncores will be set automatically to maximum number of cores in the machine. This argument is only effective if fullrmc is compiled with openmp.
Optimized current used configuration
The used optimizer optimized parameters dictionary
Add optimization structure to engine
name (str): structure user defined name
Remove optimization structure from engine
name (str): structure user defined name
Rename optimization structure from engine
name (str): structure user defined name
newName (str): structure new user defined name
Get optimized structure constraints data given user defined name or uniqueID
name (None, string): optimization name. If None then uniqueID must be given
uniqueID (None, string): if given, name will be ignored
data (dict): dictionary of all constraints data
Set used optimization given user defined name or uniqueID
name (None, string): optimization name. If None then uniqueID must be given
uniqueID (None, string): if given, name will be ignored
Set used optimization structure. This will result in resetting optimization engine and removing all existing optimizations for the previous structure
cif (string, dict): if string is given it must point to a cif file path. If a dict is given, it will be used to build an initital structure using pdbparser CrystalBuilder
scaleup (None, tuple): if given this will be used to create a bigger unitcell from the main unitcell. This can be used to refine more complex structures where inter-unitcells anisotropic correlations are present. The new constructed unitcell will be used later in the supercell creation.
supercell (tuple): defines how big of a supercell is needed
keepExpCons (boolean): whether to keep existing experimental constraints definition. If False, previously set experimental constraint will be removed.
Set structure re-definitions. Used keyword arguments are ‘atomsName’, ‘moleculesName’, ‘moleculesIndex’ and values must be lists of the same length as unitcell number of atoms. All other kwargs will be stored but ignored
Set optimizer supercell
Set optimizer optimization distance
Set optimizer supercell
Reset optimizer structure to the one as given in CIF file
Add experimental constraint to optimizer
consClass (string): type of experimental constraint to add
params (dict): Any set of parameters used to instanciate fullrmc.Constraint.PairDistributionConstraints.PairDistributionConstraint or fullrmc.Constraint.PairCorrelationConstraints.PairCorrelationConstraint or fullrmc.Constraint.RadialDistributionConstraints.RadialDistributionConstraint
Add experimental constraint to optimizer
params (dict): Any set of parameters used to update the experimental constraint
Remove experimental constraint from optimizer if existing
Add atoms distance constraint to optimizer
params (string, numpy.ndarray): distances definition parameters
Add atoms bond constraint to optimizer
Add atoms angle constraint to optimizer
Add atoms dihedral constraint to optimizer
Add atoms dihedral constraint to optimizer
Save optimizer used state. Normally this is done automatically but that can be another way to force dumping state to repository ‘state_used’ file
Load optimizer ‘state_used’. This can be invoked to restore optimizer state
Save current state in order to retrieve it later
name (str): state name to backup
Save current state in order to retrieve it later
name (str): optimizer saved state name to restore
Delete optimizer backed-up state
name (str): optimizer saved state name to be delete
Set optimizer parameters
Run optimizer
params (string, numpy.ndarray): Any set of parameters to pass to optimizer run method
Alias to optimizer_run_optimization
Set optimizer structure
saveStateKwargs (None, dict): If given this will be used to pass to ‘optimizer_backup_state’ method
params (string, numpy.ndarray): Any set of parameters to pass to optimizer set optimized structure method
Convert an optimized configuration to a stochastic statistical multiframe.
multiframe (string): the statistical multiframe to use or to create
subframe (string): the subframe name to create or to use
confName (None, string): the configuration name to use. If None, the optimizer used configuration will be set
supercell (None, tuple): the supercell size. If None, the optimization supercell will be used
contiguous (boolean): build frame from contiguous unitcell
optimizedStructure (boolean): build frame from the final optimized structure
addExperimentalConstraint (boolean): whether to add optimization experimental constraints to the created stochastic frame
addRigidConstraints (boolean): whether to add optimization rigid constraints to the created stochastic frame
RemoveExistingExperimentalConstraints (boolean): whether to remove any existing experimental constraints already set on the frame prior to adding the optimization’s ones
Bases: Engine
Coarse grains engine that is meant to be used along a normal Engine in multiframe calculations.
parent (fullrmc.Engine): fullrmc parent engine
multiframe (string): parent engine multiframe in use. It must be a nanoscopic multiframe
Parent engine multiframe in use
Parent engine multiframe subframes
Parent engine multiframe subframes to subframe index look up table
Grains weight array which indicates the number of atoms per grains
Grain size in angstrom
Multiframe structure dictionary
Number of grains.
Number of atoms as the total sum of all grains weight.
Get average number of atoms per grains
Dictionary of all cloned constraints mapping to the original constraint name in parent engine
Dictionary of subframes index keys and values are all grains indexes that belong to the subframe
Disabled. Grains_Engine shares its parent engine’s repository and must not save independently. This is a deliberate no-op; save the parent engine instead.
Set engine grains which is the replacement to set_pdb for a grain engine.
grainsElement (list): list of all grains element type
grainsWeight (list): list of all grains weight which is relative or equal to the number of atoms in a grain
moleculesIndex (list): list of grains molecule index
subframesIndex (list): list of grains subframe index that refers to the subframe from where the grain atoms are found
coordinates (numpy.ndarray): grains real coordinates
Helper method to automatically to create groups of subframe atom indexes. If add is True, created groups will be added to engine existing ones otherwise old groups will be removed.
name (None, string, list): groups name. If string is given, the same name will be given to all groups. If list is given, it must have the same length as the number of molecules in the system. If None is given, names will be set as subframe name
add (boolean): whether to add newly generated groups to old ones
Create and set grains inter-frames distance constraint. All given distances will be adjusted to system given grainSize per elements pair.
defaultLowerDistance (None, number): The default lower distance allowed. If None, defaultLowerDistance will be set to 1.5. Final defaultLowerDistance will be defaultLowerDistance + 2*grainSize
pairsDefinition (None, list, dict): list where items are lists or tuples of 3 items (first element, second element, lower distance). All distances will be automatically adjusted by adding grainSize
GE.set_distances_constraint(defaultLowerDistance=2.,
pairsDefinition={('h','c'):2.5, ('h','o'):2.75})
# constraint pairs distances for ('h','c') pair will be automatically
# adjusted to 'h' and 'c' grain sizes. Therefore ('h','c') distance
# will be set to 2.5 + h_grainSize + c_grainSize accounting for
# the maximum width of both grains. Similarly ('h','o') pairs
# distance will be adjusted and all other pairs
Set engine experimental constraints cloning those given in multiframe structure
Run method for Grains_Engine