The Monte Carlo class (Casino) is a subclass of the Molecular Mechanics (MolMech) class. The Casino class is defined in the MonteCarlo module in Yup.Models. The import statement would be some variant of: from Yup.Methods.MonteCarlo import Casino. Data Attributes Data attribute names are case-sensitive. In addition to these data attributes this class also inherits the attributes from the MolMech class. Attribute Description DownScale The step size for rotation angles and translation shifts will be scaled by this value if triggered by DownTrigger. The preset value is 0.5. DownTrigger If the fraction of moves that have been accepted falls below this value, the step size for translation and rotation will be scaled by DownScale. The preset value is 0.45. LargestMove This applies only to Grouped Monte Carlo. The center of mass of move units are allowed to move from their starting positions by no more than this quantity [Å]. The preset value is 1030 Å, which is large enough so that this limit is unlikely to come into play. However, this limit does not apply to rotation. LargestShift The step size for translation shifts is scaled by UpScale or DownScale. However, the step is not allowed to exceed this value [Å]. The preset value is 1.0 Å. LargestTurn The step size for rotation angles is scaled by UpScale or DownScale. However, the step size is not allowed to exceed this value [radians]. The preset value is PI/18 (i.e 10°). SmallestShift The step size for translation shifts is not allowed to fall below this value [Å]. The preset value is 10-3 Å. SmallestTurn The step size for rotation angles is not allowed to fall below this value [radians]. The preset value is PI/1800 (i.e 0.1°). UpScale The step size for rotation angle and translation shifts will be scaled by this value if triggered by UpTrigger. The preset value is 1.05. UpTrigger If the fraction of moves that have been accepted exceeds this value, the step size for translation and rotation will be scaled by UpScale. The preset value is 0.55. At each Monte Carlo step, each move unit is translated or rotated by an incremental quantity. This quantity is generated as a random value, positive or negative, with a maximum magnitude called the step size. There is one step size for translation and another for rotation. These step sizes are adjusted whenever the acceptance ratio falls outside a band between DownTrigger and UpTrigger. The steps are scaled by DownScale or UpScale, but the step sizes are also constrained to float inside a band: between SmallestShift and LargestShift for translation and between SmallestTurn and LargestTurn for rotation. These settings should be reconsidered if the resulting acceptance ratio falls outside the band defined by DownTrigger and UpTrigger or if the step sizes are at one limiting value or the other. Types of Moves In the Monte Carlo method, atoms are tentatively moved, the resulting change in energy is calculated, which is then used to determine if the move is to be accepted or rejected. There are three varieties of moves available: Atomic, Grouped and Axial. A system may contain all three move varieties but some combinations do not work. Atomic A move unit contains exactly one atom. Each unit is moved by translation only. The coordinates are updated incrementally. This implementation of Monte Carlo is tuned for move units containing many atoms. Thus, the Atomic variety of move is not very efficient. For example, move units are picked in proportion to the numbers of atoms they contain. The algorithm uses binary search which is unnecessarily elaborate for picking single atoms at random. Axial A move unit may contain any number of atoms. The atom numbers in each unit must form an uninterrupted range of atom numbers. With each unit, two other atoms are specified to define a rotation axis. The atoms need not be bonded and are usually not part of the move unit itself. Each move consists of rotating the unit by a randomly generated angle about the axis defined by the atom pair. The coordinates are updated by accumulated rotations with no error correction. This may be a concern for long simulations where the accumulated error may distort the conformation of the move unit. Grouped A copy of the coordinates is made at the start of the simulation; we will call this the Origin. Each move unit may contain any number of atoms that are numbered in a continuous range. Units are moved by translation and rotation, the ratio can be specified individually for each unit. Moves are accumulated as three displacements from Origin and three rotation angles relative to Origin. In a trial move, one of the six parameters is updated. The parameters are then used to calculate the transformation matrix which is then applied to Origin to yield the new coordinates. Thus, each set of coordinates is generated from Origin by one multiplication with the transformation matrix. The move units must not overlap and we do not see any reason to mix this with other varieties of moves. The transformation matrices can be useful. One use for them is as follows. Certain simuations can be carried out using a reduced representation model. The original all-atom coordinates is first converted to the simplified representation. The simulation is carried out with the simpler model. At the conclusion of the simulation, the transformation matrices are applied to the original all-atom coordinates. This yields a new set of coordinates for the all-atom model. Methods The Casino class defines the constructor function and three methods. The constructor function requires one argument, the model on which the Monte Carlo method is to be applied. This is a Model object that is constructed by a force field assembler. There are three other arguments, all of which are optional. Constructor Number of Arguments Return Value Casino 4 The new Casino object Argument Purpose Preset Value a Model object the model that is to be subjected to the molecular mechanics calculation - movers list of move units and their properties None initmove initial maximum displacement 0.1 Å initturn initial maximum rotation angle PI/180 radians (i.e 1°) The model object must be complete, i.e., the Map, Energy and Coordinates attributes must all be defined. The initial step size for translation is set to the value of initmove which is set to 0.1 Å. This will be scaled up or down whenever the acceptance ratio falls outside a defined band; see the discussion of data attributes above. The initial step size for rotation angles is set to the value of initturn which is set to PI/180 radians which is 1°. This is also rescaled during the simulation. The default value of movers is None. If left at this value, the Model will be prepared for Atomic Monte Carlo. A Casino object can created for more complex simulations by specifying a list of move units and their characteristics. Each entry in the list contains either three or five items: ( t, i, j ) or ( t, i, j, x0, x1 ). There are restrictions on these numbers: Monte Carlo Variety Fraction Translation, t First Atom Number, i Last Atom Number, j Atom Number of Axis Origin, x0 Atom Number of Axis Target, x1 Atomic t>1 0<=i<N i<=j<N ignored ignored Axial t<0 0<=i<N i<=j<N ignored ignored Grouped 0<=t<=1 0<=i<N i<=j<N 0<=x0<N 0<=x1<N x1!=x0 where N is the number of atoms in the system. Not all combinations will work and there situations in which move units are expected to overlap and other situations where overlapping move units will yield incorrect results. The Metropolis method carries out a monte carlo calculation using the Metropolis method. Only the first argument is required. Method Argument Keywords Return Value Metropolis "numstep", "limit" - Argument Type Preset Value numsweep Integer - limit None, a group AtomMap, or a list of two integers None startTemp float 300 K finalTemp float 300 K Each sweep consists of as many moves as the number of move units. The move units are picked at random so not all units are moved in each sweep, some are picked more than once, but in the long run each unit will be picked in proportion to the number of atoms it contains. The simulation will be carried out at a formal temperature that varies linearly from startTemp to finalTemp. Both parameters are set to 300K. Please see the Targeted Simulation section of the Introduction to see how to set limit. Only the move units that are entirely enclosed by the specified group will be moved. A summary of the simulation is printed at the end of the simulation. This shows the number of accepted and rejected moves and the number of rotations and translations. These numbers are summed for all move units. Example >>> from Yup.Models.TestTube.FFA import makecircle >>> from Yup.Methods.EnerMinim import Minimizers >>> from Yup.Methods.MolDynam import Motors >>> >>> M = makecircle( 100 ); O = Minimizers( M ); D = Motors( M ) >>> >>> D.set_ThermMethod( 'BERENDSEN' ) >>> D.ThermalizationInterval = 25 >>> minimize = O.SteepestDescent >>> dynamics = D.Verlet >>> >>> minimize( 1000 ); dynamics( 10000, 300.0 ); dynamics( 10000, 300.0 ); dynamics( 10000, 1.0 ); minimize( 1000 ) In this example, we start with the required imports: the makecircle() method from the TestTube force field assembler, the Minimizers class from the Energy Minimization module and the Motors class from the MolDynam module. The makecircle() method assembles the force field for a circular chain of beads, and the example asks for a chain of 100 beads and the Model that is returned is saved in the variable M. M is then passed to the Minimizers() constructor function and the object that is returned is then saved in the variable O. A Motors object is also constructed and saved in the variable D. The thermalization method is set to 'BERENDSEN' using the set_ThermMethod() method and the thermalization interval is set to 25. The steepest descent method is selected from the EnerMinim class and saved to the variable minimize. Similarly, the Verlet method is selected from the Motors object and assigned to the variable dynamics. The calculation consists of 1000 steps of energy minimization at the start and again at the end of the procedure. In between, molecular dynamics simulations are carried out in three blocks of 10000 steps each. In the first block the temperature is raised from the starting value which is 0K to 300K. In the next block the temperature is maintained at 300K. In the final block the temperature target is lowered to 1K. The showstatistics method prints the vital statistics for the last Monte Carlo simulation. Obviously, this method must be called at the end of a simulation; the numbers will be reset for the next simulation. Method Argument Return Value showstatistics - - The output is a table containing the following items for each move unit: [1] Unit#(^:$), the unit number and the first and last atom numbers that it contains; [2] FracTrans, the fraction of translation; [3] #Pass, number of moves that were accepted; [4] #Fail, the number of moves that were rejected; [5] Stepsize, the step size for translation and [6] Turnsize, the step size for rotation. The showtransform method prints the transform matrices for units that are set to use the Grouped moves. Method Argument Return Value showtransform - - Each Grouped move unit yields one transformation matrix printed to high precision. The output can be imported into a spreadsheet. The transforms method, takes no argument, and it returns the transformation matrix. Introduction Molecular Mechanics Energy Minimization Molecular Dynamics Monte Carlo