Versions Information

Must know

• fullrmc supported version is always the newest one. Older version are never supported as updating is very simple.
• fullrmc uses pdbparser library to parse input pdb files and to visualize system’s atomic structure using VMD. VMD which stands for Visual Molecular Dynamics is a free software for displaying and animating large molecular systems.
• pdbparser in general automatically detects VMD executable when installed. fullrmc will work fine without VMD, but make sure it’s installed if you want to use the convenient visualize method of fullrmc’s Engine.
• Unless Engine set_molecules_indexes method is used explicitly, molecules are classified by parsing the structure ‘.pdb’ file Residue name, Residue sequence number and Segment identifier attributes. Therefore a molecule is the collection of all atoms sharing the same three later attributes value.

Installation

Here we describe two methods to installing fullrmc.

1. The first method is by using pip. If you don’t know what pip is and you are lazy enough not to read through the documentation, pip supports installing from PyPI, version control, local projects, and directly from distribution files. To install pip download get_pip.py file and run the following from the command line.

   python get_pip.py
   

2. The second method is by fullrmc’s cloning the source code and repository from github and then compiling the extension files in place.

For your general understanding, fullrmc requires the following:

1. Python (>= 2.7 and < 3) Starting from fullrmc 4.x.y python 3 is supported
2. NumPy (lowest version tested is 1.7.1)
3. cython (lowest version tested is 0.21.1)
4. matplotlib (lowest version tested is 1.4)
5. pdbparser (lowest version tested is 0.1.2 - 0.1.3 is used starting from fullrmc 0.3.0 - 0.1.4 is used starting from fullrmc 1.0.0 - 0.1.5 is used starting from fullrmc 1.0.1 - 0.1.7 is used starting from fullrmc 4.0.0)
6. pysimplelog (lowest version tested is 0.1.7 - 0.1.4 is used starting from fullrmc 1.2.0 - 0.2.0 is used starting from fullrmc 4.0.0)
7. pyrep (lowest version tested is 1.0.2 is used starting from fullrmc 2.0.0 - 1.0.3 is used starting from fullrmc 3.0.0 - 1.0.4 is used starting rom fullrmc 3.1.0 - 3.1.0 is used starting from fullrmc 4.0.0)

Installation using pip:

Installing fullrmc with pip is done in two steps. Firstly install numpy and cython manually and ensure that they meet with fullrmc’s version requirement.

pip install -U "numpy>=1.17.4"
pip install -U "cython>=0.29.14"

When you already have a working up-do-date installation of numpy and cython, you can proceed to installing fullrmc. The rest of the dependencies will be automatically installed and updated while fullrmc is being installed.

pip install fullrmc

Installation by cloning github repository:

• Ensure all fullrmc required packages are installed and up-do-date by executing the following python script:

# check whether all packages are already installed
from __future__ import print_function
from pkg_resources import parse_version as PV
for name, ver in [('numpy'      ,'1.17.4') ,
                  ('cython'     ,'0.29.14'),
                  ('pyrep'      ,'3.1.0') ,
                  ('pdbparser'  ,'0.1.7') ,
                  ('pysimplelog','2.0.0') ,
                  ('matplotlib' ,'2.2.3'  )]:
    try:
        lib = __import__(name)
    except:
        print('%s must be installed for fullrmc to run properly.'%(name))
    else:
        if PV(lib.__version__) < PV(ver):
            print('%s installed version %s is below minimum suggested version %s. Updating %s is highly) recommended.'%(name, lib.__version__, ver, name)
        else:
            print('%s is installed properly and minimum version requirement is met.'%(name))

• Locate python’s site-packages by executing the following python script:

  from __future__ import print_function
  import os
  os.path.join(os.path.dirname(os.__file__), 'site_packages')
  

• Navigate to site_packages folder and clone git repository from command line:

cd .../site_packages
git clone https://github.com/bachiraoun/fullrmc.git

• Change directory to …/site_packages/fullrmc/Extensions. Then compile fullrmc extensions from command line as the following:

cd .../site_packages/fullrmc/Extensions
python setup.py build_ext --inplace

Versions

Latest stable version source code: https://github.com/bachiraoun/fullrmc

Latest pypi installable version: https://pypi.python.org/pypi/fullrmc/

Version 0.1.0:

This version is not published.

Modules and definitions:

1. Selectors: RandomSelector WeightedRandomSelector DefinedOrderSelector DirectionalOrderSelector
2. Constraints: InterMolecularDistanceConstraint IntraMolecularDistanceConstraint BondConstraint BondsAngleConstraint ImproperAngleConstraint PairDistributionConstraint PairCorrelationConstraint
3. Generators: TranslationGenerator TranslationAlongAxisGenerator TranslationAlongSymmetryAxisGenerator TranslationTowardsCenterGenerator TranslationTowardsAxisGenerator TranslationTowardsSymmetryAxisGenerator TranslationAlongSymmetryAxisPath RotationGenerator RotationAboutAxisGenerator RotationAboutSymmetryAxisGenerator RotationAboutSymmetryAxisPath DistanceAgitationGenerator AngleAgitationGenerator

Version 0.2.0:

This is the first officially published version.

New Modules and definitions:

1. Selectors: SmartRandomSelector
2. Constraints: AtomicCoordinationNumberConstraint
3. Generators: SwapPositionsGenerator

Known bugs and issues:

1. Boundary conditions handling for all non cubic, tetragonal nor orthorhombic systems is prone to distances calculation errors caused by pdbparser (<=0.1.2).

Version 0.3.0:

Starting from this version, pdbparser (>=0.1.3) is used.

Fixes and improvements:

1. Periodic boundary conditions handling fixed and separated from pdbparser.
2. InterMolecularDistanceConstraint squared deviation computation changed from square law to absolute value. Therefore small values are not under-represented in the total squared deviation calculation.
3. InterMolecularDistanceConstraint ‘flexible’ flag added.

Version 0.3.1:

Fixes and improvements:

1. Erroneous wx imports from thfSimulation Example is removed.
2. PairDistributionConstraint and PairCorrelationConstraint check_experimental_data merged and sorted distances bug fixed.
3. PairDistributionConstraint and PairCorrelationConstraint set_limits bug fixed.
4. Engine add_group method allows list, set, tuples as well as integers.

Version 0.3.2:

Fixes and improvements:

1. PairDistributionConstraint and PairCorrelationConstraint binning precision fixed. Histogram compiled C code adjusted accordingly.
2. AtomicCoordinationNumberConstraint set_coordination_number_definition method error message made more clear.
3. AtomicCoordinationNumberConstraint compiled C++ code boundary conditions distances computation fixed for multiple box separation.

Version 0.3.3:

New Modules and definitions:

1. SwapCentersGenerator

Version 0.4.0:

New Modules and definitions:

1. StructureFactorConstraint added computing Static Structure Factor
2. ReducedStructureFactorConstraint added computing Reduced Static Structure Factor

Fixes and improvements:

1. PairDistributionConstraint and PairCorrelationConstraint plot Y axis label units added.
2. swap example changed to atomicSimulation and S(q) added to the fitting along with G(r)
3. thfSimulation example change to molecularSimulation

Version 1.0.0:

This is a main version change from 0.x.y to 1.x.y and that’s because non-periodic boundary conditions are now implemented. Starting from this version shape function correction can be used. For non-periodic boundary conditions, very big box with periodic boundaries is automatically set and system shape function is estimated to correct for the fixed \(\rho_{0}\) global density approximation.

Some testing were done prior to publishing this version and it was found out that computing angles for BondsAngleConstraint can in some cases be wrong. We recommend updating to this version if BondsAngleConstraint is needed for fitting molecular systems.

Starting from this version, pdbparser (>=0.1.4) is used.

New Modules and definitions:

1. fullrmc.Constraints.Collection package added along with ShapeFunction
2. Engine numberDensity added. Used to set correct volume and density when InfiniteBoundaries are used
3. fullrmc.Core.Collection.smooth function added. It can be used to smooth out any 1D data. This is useful for noise experimental data

Fixes and improvements:

1. BondAngles calculation bug fixed
2. Constraints all squared deviations attributes and methods changed to standard error to conserve the generality
3. Engine chiSquare attributes and methods changed to total standard error to conserve the generality
4. Logger levels added
5. rebin core method check argument added
6. StructureFactorConstraint and ReducedStructureFactorConstraint experimentalQValues set as property

Version 1.0.1:

Starting from this version, pdbparser (>=0.1.5) is used. There is no bugs fixed in this version comparably to version 1.0.0. This version corrects for cell visualization compatibility between fullrmc and VMD. VMD cell plugin uses a, b, c, unitcell parameters (the lengths of vectors A, B and C the 3D-vectors of the unitcell sides with the convention that A is parallel to the x-axis) and alpha, beta, gamma (the angles of the unit cell) for non-orthorhombic unitcells. This version uses cell plugin no more but draw the boundary conditions vectors directly. Also visualization method ‘boxToCenter’ flag is added to correct for box visualization shifts by translating boundary conditions vectors’ centre to atom coordinates one.

Version 1.1.0:

Several levels of abstractions are made allowing multiple core computations using openmp. Nevertheless more testing is needed and therefore the current version is published as single core still. AtomicCoordinationNumberConstraint uses python objects which makes it very slow, it must be revisited.

New Modules and definitions:

1. Constraint computation cost property added. This is used at engine runtime to minimize computations and enhance performance by computing less costly constraints first.

Fixes and improvements:

1. BondsAngleConstraint computing angle right vector normalization bug fixed.
2. ImproperAngleConstraint computing improper vector bug fixed.

Version 1.2.0:

Starting from this version, running fullrmc on multicore and multiprocessor computers is possible. Also, pysimplelog (>=0.2.1) is used. Isolated system in non-periodic boundary conditions are treated correctly as in an infinte box using inifinite boundary conditions instead of a very big box with periodic boundaries.

New Modules and definitions:

1. AtomicCoordinationNumberConstraint completely reimplemented and optimized. Coordination number definition is re-formatted allowing any type of core’s and shell’s atoms. This new implementation computes mean coordination number per shell definition rather than per atom. Fractional coordination numbers are allowed and this implementation benefits from a tremendous performance increase of 1000 times compared to the old one.
2. Engine.run method ‘restartPdb’ and ‘ncore’ arguments added.

Version 1.2.1:

No bugs fixed but some examples corrected.

Version 2.0.0:

This is a main version change from 1.x.y to 2.x.y. Starting from this version engine is no more a single file but a pyrep repository. Using a repository engine instead of a single file has many advantages. The first and more important advantage is the limitation of accessing and saving single big engine files when the simulated atomic system is big. The second advantage is the introduction of the concept of engine frames. Frames can be used to build a fitting history or even better to creating a statistical structural solution rather than a single structure one which is prone primarily to overfitting and other errors. Also, repository engine’s insure a sort of backwards compatibility and files can be retrieved when updating fullrmc’s versions. Implementation wise, switching from single file to repository is the ground layer to taking fullrmc to the next level of super-computing. Engine repository is not a binary black box file but a directory or a folder that one can browse. It’s advisable not to manually delete or add files or folders to the repository. Interacting with fullrmc.Engine instance is what one should do to creating or updating engine’s repository. The transition to fullrmc 2.x.y. should be done seemlessly at the end of the user except for small modifications that were made and that are listed below.

Modifications:

1. Engine: Several modification happened to fullrmc.Engine class definition.

   • Instanciating engine arguments have changed. We found that it’s a bad practice to set the pdb structure, the constraints, the groups and all other attributes at the engine instanciation. Therefore, now engine’s instanciation takes more appropriate arguments such as the engine’s repository path, the frames, the log file path and whether to delete a found engine at the given path and start fresh using freshStart flag.
   • Engine.is_engine method is added to check whether a given path is a fullrmc.Engine repository.
   • Engine frames related methods are also added to manipulate and switch between frames.
   • Engine.run method takes no more savePath argument, as the path has to be the repository. In case one wants to save in a new repository, he should save the engine first using Engine.save method and then run the engine using Engine.run method.

2. Constraint: We also found that constraints must not be allowed to change engine and therefore Constraint.set_engine method is now deprecated. Also Constraints are now instanciated without engine argument. Constraint’s engine is set automatically when a constraint is added to an engine.

Fixes and improvements:

1. abs function changed in all compiled files as it was creating rounding issues on some operating systems.
2. arcos function cliped for floating errors in angles compiled file.
3. InterMolecularDistanceConstraint: Computing constraint data in function single_atomic_distances_dists of compiled atomic_distances fixed.
4. BondConstraint: bondsMap fixed from causing definition conflicts if set multiple times.
5. BondsAngleConstraint: anglesMap fixed from causing definition conflicts if set multiple times.
6. ImproperAngleConstraint: anglesMap fixed from causing definition conflicts if set multiple times.

Version 3.0.0:

This is a main version change from 2.x.y to 3.x.y where pyrep (>=1.0.3) is used. Thusfar until versions 2.x.y, system’s number of atoms is fixed throughout the whole simulation. Starting from this version, fullrmc allows dynamically removing atoms from the system upon fitting. This is a revolutionary functionality enabling the reproduction of defects in systems.

New Modules and definitions:

1. DihedralAngleConstraint implemented to control dihedral angles.
2. AtomsCollector implemented allowing the ability of dynamically remove and add re-insert atoms to the system.
3. AtomsRemoveGenerator implemented to generate atoms removing from system upon fitting.
4. EmptyGroup added to host Removes generators.

Modifications:

1. all cython modules are completely de-pythonized.
2. all angle constraints respect the same implementation and interface design.

Version 3.0.1:

New Modules and definitions:

1. Plot method added to all of BondConstraint, BondsAngleConstraint, DihedralAngleConstraint and ImproperAngleConstraint.

Fixes and improvements:

1. DihedralAngleConstraint FRAME_DATA fixed which was preventing constraint from saving to pyrep repository.

Version 3.0.2:

New Modules and definitions:

1. Redundant objects global container mechanism added. This will sometimes reduce some engine’s attributes size, allowing fast saving and loading of data.

Fixes and improvements:

1. MoveGeneratorCombinator bug from latest update fixed.
2. SwapGenerator is not allowed to be collected or combined with other generators. Also swapList will update automatically upon removing and releasing atoms.
3. RemoveGenerator is not allowed to be collected or combined with other generators.
4. MLSelection, refine and explore examples BiasedEngine fixed

Version 3.1.0:

Starting from this version, it is possible to custom set atoms weight for all of PairDistributionConstraint, PairCorrelationConstraint, StructureFactorConstraint and ReducedStructureFactorConstraint. Also starting from this version, pysimplelog (>=0.3.0) and pyrep (>=1.0.4) are used.

New Modules and definitions:

1. All constraints export data method added.
2. All constraints plot method added.
3. IntraMolecularDistanceConstraint added again after being removed in early versions.

Fixes and improvements:

1. Engine repository ACID flag is changed to False as it’s not needed.
2. StructureFactorConstraint and ReducedStructureFactorConstraint atoms removal bug fixed.
3. Computing standard error for IntraMolecularDistanceConstraint and InterMolecularDistanceConstraint is optimized for big systems and constraint’s definition. Calculation time is thousands of times faster for extended definitions.

Version 3.1.1:

Some bugs are fixed and documentation is revisited.

Fixes and improvements:

1. Engine set_number_density method PeriodicBoundaries bug fixed.
2. StructureFactorConstraint set_weighting xrays and neutron recognized.

Version 3.1.2:

Raised issue bug fixed

Version 3.1.3:

Some bugs are fixed and documentation is revisited.

Version 3.2.0:

Raised issue bug fixed

Version 3.3.0:

Raised issue bug fixed

Version 4.0.0:

This version is not published.

Version 4.0.1:

Starting from this version, fullrmc has become grid computing capable. multiframe is implemented to generate a statistical solution of multiple frames instead of a single frame solution. Along with this version, an instance of fullrmc will be available on a cloud service that can be used to launch fullrmc and perform multiframe computations. We will update all user in the Q&A group when and where this service will be available

New Modules and definitions:

1. MultiframeUtils module added which will be used to launch fullrmc on computation grids
2. ExperimentalConstraints plot and data export methods factored

Fixes and improvements:

1. StructureFactorConstraint scale factor bug fixed
2. PairCorrelationConstraint scale factor bug fixed
3. Engine run method explore bug fixed
4. Amputation number density bug fixed for InfiniteBoundaryConditions

Version 4.1.0:

Starting from this version, fullrmc stochastic Engine is codify-able. This is a new capability that allows exporting the engine across all systems and operating system without worrying about serialization compatibility. Also, starting from this version, fullrmc requires pylocker to be installed.

New Modules and definitions:

1. Group ‘name’ property added
2. Engine ‘codify’ method added
3. constraints number of tried and accepted moves are tracked now
4. constraints advanced plotting and export helper method

Fixes and improvements:

1. Engine remove constraint bug fixed
2. OrientationGenerator bugs fixed
3. DirectionalOrderSelector bug fixed
4. BondConstraint add_bond method deprecated. set_bonds method modified for performance reasons. bondsDefinition property added.
5. BondsAngleConstraint add_bond method deprecated. set_bonds method modified for performance reasons. anglesDefinition property added.
6. DihedralAngleConstraint add_bond method deprecated. set_bonds method modified for performance reasons. anglesDefinition property added.
7. ImproperAngleConstraint add_bond method deprecated. set_bonds method modified for performance reasons. anglesDefinition property added.
8. PairDistributionConstraint set_atoms_weight dump to repository bug fixed