To check and request fullrmc on the cloud, visit fullrmc’s website and contact info@fullrmc.com for any questions.

Use the cloud

fullrmc runs a stochastic engine that runs as a sequential process. To speed up the calculation for big systems, pthreads are used to parallelize certain parts of the computation blocks. This turns out to be beneficial when the number of atoms in the system is big enough to compensate for the overhead of launching the parallel processing on every and each step.

On the other hand when the studied atomic system is constituted of a mixture of different structures (distribution of nanoparticles size, local structures and nano-grains, distribution of structure faults, interface structures, etc.) and systems then a single atomic system simulation will never be enough to get an accurate solution. For that particular reason in fullrmc we introduce the concept of ‘multiframe’ and we use softgrid to enable running fullrmc’s multiframe on any set of connected commodity hardware to perform synchronous and asynchronous multiframe computation. See Run Modes for an explanation of the statistical, mesoscopic, and nanoscopic modes this enables.

softgrid is not open sourced and it can’t be distributed along with fullrmc. Therefore fullrmc softgrid enabled will be available as a software as a solution on cloud infrastructures such as Microsoft AZURE, Amazon AWS, Akamai Linode, etc.

MultiframeUtils contains helper classes to run and build fullrmc multiframe stochastic engine structures.

WorkersManagement is used on a softgrid worker to run a multiframe’s subframes concurrently in statistical, mesoscopic or nanoscopic mode.

MultiframeStructureBuilder is used to reorganize a multiframe’s subframes’ atom coordinates into a single, coherent nanoscale structure.

fullrmc.MultiframeUtils.generate_random_float()

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

fullrmc.MultiframeUtils.log_transfer_errors(func)

WorkersManagement method decorator that catches any exception raised by the decorated method, logs it and transfers it to the connected executor or orchestrator, then disconnects (executor case) or stops (orchestrator case).

Parameters:

1. func (function): The WorkersManagement bound method to wrap.

Returns:

1. wrapper (function): The wrapped method that transparently forwards to func and handles its exceptions.

class fullrmc.MultiframeUtils.WorkersManagement(repoTimeout=10, requestTimeout=3600)

Bases: object

Used by a remote softgrid worker to run a fullrmc stochastic engine.

Parameters:

1. repoTimeout (number): The engine’s repository read/write lock timeout in seconds.

2. requestTimeout (number): The maximum time in seconds to wait for a request to be fulfilled before giving up.

from fullrmc.Engine import Engine
from fullrmc import MultiframeUtils

# create engine
ENGINE = Engine().load(path)

# run on grid
WM = MultiframeUtils.WorkersManagement()
WM.start(engine=ENGINE, multiframe='size_distribution', orchestrator=None)

# run statistical
WM.run_statistical(nCycle=10, numberOfSteps=1000, saveFrequency=1)

# run mesoscopic
WM.run_mesoscopic(nCycle=200, firstNAccepted=1, subframesWeight=None, numberOfSteps=100, saveFrequency=10)

# run nanoscopic
WM.run_nanoscopic(nCycle=200, numberOfSteps=1000, saveFrequency=1)

start(engine, multiframe, orchestrator=None, workerRequestLoopTimeout=43200, killAtStop=None, gridLogKwargsUpdate={'logTypes': {'execution_finished': {'fileFlag': False, 'stdoutFlag': False}, 'execution_started': {'fileFlag': False, 'stdoutFlag': False}, 'result': {'fileFlag': False, 'stdoutFlag': False}}})

Start a grid computation session for a multiframe. This connects to (or creates) a softgrid orchestrator, launches one worker per subframe, and loads the corresponding stochastic engine subframe onto each worker.

Parameters:

1. engine (fullrmc.Engine): The stochastic engine instance whose used frame must be a multiframe.

2. multiframe (string): The multiframe name to distribute across workers, one subframe per worker.

3. orchestrator (None, softgrid.Orchestrator): The orchestrator to connect to. If None, a new local orchestrator is created.

4. workerRequestLoopTimeout (number): The maximum time in seconds a worker’s request loop is allowed to run for.

5. killAtStop (None, bool): Whether launched workers must be killed when this instance’s stop() is called. If None, the orchestrator’s default behavior is kept.

6. gridLogKwargsUpdate (dict): Logger configuration update passed to the orchestrator to control which softgrid log types are printed to stdout or written to file.

stop(kill=None)

Stop WorkersManagement by disconnecting from the softgrid computation.

Parameters:

1. kill (None, bool): Whether to also kill the connected workers upon disconnecting. If None, the killAtStop value given at start() time is used instead.

run_nanoscopic(nCycle=100, numberOfSteps=10000, updateFrequency=10, moveAtoms=True, moveSubframes=True, cycleMinSteps=True, subframeMinSelected=0, subframeMinAccepted=0, optimize=True, translation=5, rotation=10, swap=True, saveFrequency=10, cycleTimeout=3600)

Run all remote subframes as a single, whole nanoscopic structure. Subframes’ atomic configurations are treated as a connected system to compute the stochastic engine’s total standard error. Unlike the mesoscopic computation, this nanoscopic computation takes correlations between subframes into account.

Parameters:

1. nCycle (int): Number of stochastic engine cycles.

2. numberOfSteps (int): Number of steps per cycle. If moveAtoms is False, this parameter is ignored.

3. updateFrequency (int): Frequency, in number of accepted steps, at which subframes communicate back and update all constraints’ nanoscopic data. If moveAtoms is False, this parameter is ignored.

4. moveAtoms (boolean): Whether to create independent moves within each and every subframe, enhancing short range correlations.

5. moveSubframes (boolean): Whether to move each subframe independently as a whole grained entity, enhancing long range correlations.

6. cycleMinSteps (boolean, int): Minimum number of moveSubframes steps in a cycle before the cycle is finished. If True, cycleMinSteps is automatically set to the number of subframes. If moveSubframes is False, this parameter is ignored.

7. subframeMinSelected (int, list): Minimum number of times a subframe must be selected for a move before a cycle is finished. If moveSubframes is False, this parameter is ignored.

8. subframeMinAccepted (int, list): Minimum number of times a subframe move must be accepted before a cycle is finished. If moveSubframes is False, this parameter is ignored.

9. optimize (boolean): Whether to optimize parameters during stochastic engine runtime. Optimization parameters are defined separately in the engine constraints.

10. translation (None, number): Grains engine groups’ translation amplitude. If moveSubframes is False, this parameter is ignored.

11. rotation (None, number): Grains engine groups’ rotation amplitude in degrees. If moveSubframes is False, this parameter is ignored.

12. swap (boolean): Whether to allow swapping subframes’ center positions. If moveSubframes is False, this parameter is ignored.

13. saveFrequency (int): Frequency, in cycles, at which all subframes are saved.

14. cycleTimeout (None, integer): Estimated time, in seconds, for the stochastic engine to perform one cycle across all frames on remote workers. A timeout error is raised if cycleTimeout is exhausted before all workers finish the cycle’s work.

run_mesoscopic(nCycle=10000, firstNAccepted=1, numberOfSteps=100, subframesWeight=10, driftTolerance=1, rescaleLimit=1, allowStatistical=True, optimize=True, saveFrequency=10, cycleTimeout=900)

Run all remote subframes as a single, whole mesoscopic structure. Subframes’ weighted (subframesWeight) atomic configurations are used to compute the stochastic engine’s total standard error. Subframes’ constraints also use subframesWeight prior to computing constraints’ standard error. This computation is valid under the assumption that all subframes might exist in the measured and modeled atomic system, but that they are far enough from each other to neglect any cross-structural interactions and correlations.

Parameters:

1. nCycle (int): Number of stochastic engine cycles.

2. firstNAccepted (int): Number of accepted moves on subframes before returning the result.

3. numberOfSteps (int): Maximum number of steps per cycle.

4. subframesWeight (None, boolean, integer, list): Weights of subframes contributing to experimental constraints. If None, subframes’ weight is fixed to 1./numberOfSubframes. If False, weights are used as is. If True, weights are updated after each cycle using non-negative least squares with the added condition that all weights must sum to 1. If integer, it is the frequency, in number of cycles, at which weights are updated. If list, it is the fixed, user-defined weight for every and each subframe. Subframes’ priors are always computed after every and each cycle. If updated weights happen to be all 0, or only one subframe’s weight is non-zero, weights are automatically rescaled to 1./numberOfSubframes.

5. driftTolerance (integer): Used to avoid updated subframesWeight drift and divergence. Weights are checked for any sudden jump (increase) or drop (decrease) that doubles or halves the previous cycle’s frame weight. If drift occurs, the previous cycle’s subframesWeight is used instead. driftTolerance defines the number of successive cycles of weight drift allowed before stopping execution.

6. rescaleLimit (int): Defines the minimum number of subframes with a computed weight of 0 that triggers an automatic rescale. When the number of subframes with weight 0 is equal to or greater than rescaleLimit, all subframes’ weights are automatically adjusted and rescaled to 1./numberOfSubframes.

7. allowStatistical (boolean, int, list): Whether to allow non-participating subframes within the mesoscopic structure (0 weight) to run statistically, giving them a chance to catch up and get re-integrated into the whole structure. If True is given, allowStatistical is automatically set to the given numberOfSteps. If an integer is given, it must be >=0. If a list is given, it must have the same number of items as the number of subframes, with values that are booleans or integers.

8. optimize (boolean): Whether to optimize parameters during stochastic engine runtime. Optimization parameters are defined separately in the engine constraints.

9. saveFrequency (int): Frequency, in cycles, at which all frames are saved.

10. cycleTimeout (None, integer): Estimated time, in seconds, for the stochastic engine to perform one cycle across all frames on remote workers. A timeout error is raised if cycleTimeout is exhausted before all workers finish the cycle’s work.

run_statistical(nCycle=100, numberOfSteps=1000, updateLoss=True, optimize=True, saveFrequency=1, cycleTimeout=3600)

Run all remote subframes as totally independent structures.

Parameters:

1. nCycle (int): Number of total independent cycles.

2. numberOfSteps (int): Number of steps per cycle.

3. updateLoss (boolean): Whether to train the loss function during stochastic engine runtime. This only takes effect if the chosen loss is not static but machine-learning enabled.

4. optimize (boolean): Whether to optimize parameters during stochastic engine runtime. Optimization parameters are defined separately in the engine constraints.

5. saveFrequency (int): Frequency, in cycles, at which all frames are saved.

6. cycleTimeout (None, integer): Estimated time, in seconds, for the stochastic engine to perform one cycle across all frames on remote workers. A timeout error is raised if cycleTimeout is exhausted before all workers finish the cycle’s work.

save()

Call all remote subframes to save.

class fullrmc.MultiframeUtils.MultiframeStructureBuilder(engine, multiframe, boundaryConditions=None, numberDensity=None)

Bases: object

Multiframe structure builder used to reorganize subframes’ atom coordinates and create a single, coherent multiframe structure out of all of its subframes’ atoms. This is mostly used for nanoscale computations.

Parameters:

1. engine (fullrmc.Engine): The fullrmc engine.

2. multiframe (str): The engine’s multiframe.

3. boundaryConditions (None, boundaryConditions): The multiframe structure’s boundaryConditions. If None, this is computed using the provided numberDensity.

4. numberDensity (None, number): If boundaryConditions is given, this is not used. Otherwise, numberDensity is used to create the boundaryConditions. Default value is half of pure water’s number density.

from fullrmc.MultiframeUtils import MultiframeStructureBuilder
from fullrmc.Globals import WATER_NUMBER_DENSITY
MSB = MultiframeStructureBuilder(engine=E, multiframe='multi', boundaryConditions=None, numberDensity=WATER_NUMBER_DENSITY/2.)
MSB.build_random()
pdb = MSB.get_pdb()
pdb.visualize()

set_multiframe(multiframe)

Set the multiframe.

Parameters:

1. multiframe (str): The engine’s multiframe.

set_boundary_conditions(boundaryConditions, numberDensity=None)

Set boundary conditions and number density. If both boundaryConditions and numberDensity are None, the multiframe structure must be nanoscopic.

Parameters:

1. boundaryConditions (None, boundaryConditions): The multiframe structure’s boundaryConditions. If None, this is computed using the provided numberDensity.

2. numberDensity (None, number): If boundaryConditions is given, this is not used. Otherwise, numberDensity is used to create the boundaryConditions.

translate(realCoordinates, vector=None)

Translate given real space coordinates within boundary conditions.

Parameters:

1. realCoordinates (numpy.ndarray): The atoms’ coordinates to translate.

2. vector (None, numpy.ndarray): The translation vector to apply. If None, a random vector towards the positive quadrant is generated.

Returns:

1. coordinates (numpy.ndarray): The translated coordinates.

2. vector (numpy.ndarray): The translation vector used.

rotate(realCoordinates, rotationAxis=None, rotationAngle=None)

Rotate given real space coordinates.

Parameters:

1. realCoordinates (numpy.ndarray): The atoms’ coordinates to rotate.

2. rotationAxis (None, numpy.ndarray): The rotation axis vector to use. If None, a random unit vector is generated.

3. rotationAngle (None, number): The rotation angle, in radians, to use. If None, a random angle is generated.

Returns:

1. coordinates (numpy.ndarray): The rotated coordinates. If realCoordinates has one atom or fewer, rotation is a no-op and the input coordinates are returned unchanged.

2. rotationAxis (None, numpy.ndarray): The rotation axis vector used, or None if realCoordinates has one atom or fewer.

3. rotationAngle (None, number): The rotation angle used, or None if realCoordinates has one atom or fewer.

get_box_coordinates(realCoordinates)

Transform real space coordinates to box space coordinates.

Parameters:

1. realCoordinates (numpy.ndarray): The atoms’ coordinates to transform.

Returns:

1. boxCoordinates (numpy.ndarray): The box coordinates.

get_real_coordinates(boxCoordinates)

Transform box space coordinates to real space coordinates.

Parameters:

1. boxCoordinates (numpy.ndarray): The atoms’ coordinates to transform.

Returns:

1. realCoordinates (numpy.ndarray): The real coordinates.

build_random(lowerDistance=2.0, maxTrials=50000, shuffle='big first', translate=True, rotate=True, moveFirst=True)

Randomize subframes’ structures within the boundary conditions box by applying translations and rotations.

Parameters:

1. lowerDistance (number): Minimum contact distance.

2. maxTrials (integer): Maximum number of trials to insert a subframe.

3. shuffle (string, list, tuple, boolean): Whether to shuffle frames before insertion. If string, ‘big first’ or ‘small first’ are accepted. If list, it must be a list of integers ranging from 0 to the number of subframes. Otherwise, if True, subframes are randomly shuffled for insertion.

4. translate (boolean): Whether to apply translations.

5. rotate (boolean): Whether to apply rotations.

6. moveFirst (boolean): Whether to apply a random translation and rotation to the first inserted subframe.

update_multiframe_coordinates(force=True)

Push the built multiframe structure coordinates to the subframes.

Parameters:

1. force (boolean): Whether to force re-updating the coordinates if they were already updated.

get_pdb()

Get a single pdb from the multiframe structure.

Returns:

1. pdb (pdbparser.pdbparser): The pdb instance.