Introduction Data Preparation Force Field Assembly Calculate The Yup.Models.Emmental.Calculate module provides five functions designed to optimize the potential energy function of an Emmental model. The objective is to optimize the fitting of the model in the density map. Most of the functions customize the standard molecular mechanics methods provided in the Yup.Methods sub-package. The customization takes the form of adjusting the range of the force field that is derived from the density map. The standard molecular mechanic methods (the modules in Yup.Methods) can also be applied to Emmental models. The field that is derived from the density map is represented by the SwissCheeseX term. In this term, we have a collection of attractive holes that are each fixed in space. Each hole corresponds to a voxel with a density above a threshold value and the depth of the hole is proportional to the density. Each hole has the same inner and outer radii. An atom that is within range of the outer radius of a hole will feel an attraction towards it. In the following, we will refer to radius annealing which is when the outer radius is gradually reduced from an initial high value to a value close to the inner radius. This is done throughout an Energy Minimization, Molecular Dynamics or Monte Carlo procedure. Typically, the molecule is allowed to sample the conformations available to it when the outer radius is high, i.e, each atom feels the influence of many holes. The strongest influence will be from the closest and/or deepest hole. As the annealing procedure proceeds, the outer radius is gradually reduced. Thus, at the end of the procedure, each atom will feel the influence from only the nearest holes. These functions takes advantage of the facility to insert user events into the flow of each procedure. See Molecular Mechanics. The radius annealing procedure is available in two versions, linear and non-linear, which describes the radius reduction profile. AnnealEM The AnnealEM() function, also known as Refine(), takes one to nine arguments and it carries out a radius annealing as part of an energy minimization procedure using the steepest descent method. Argument Type Preset Value Description model Model The Emmental Model object numsteps integer or None None total number of energy minimization steps, if None: set equal to stepfactor times the rounded number of atoms. numstages integer or None None number of steps between adjustment of the outer radius towards its final value, if None: numsteps / 100, i.e., the outer radius will be adjusted in numstages stages over the numsteps steps of energy minimization. initialhold None or integer None number of initial steps in which the outer radius is held at a fixed value while the energy is minimized, if None: numsteps / 10 outratio float 5.0 initial value of the ratio between the outer and the inner radius of the holes. finalratio None or float None final value of the ratio between the outer and the inner radius of the holes, if None: set it to the ratio of the radius of the smallest sphere that encloses a voxel and the inner radius. divscale float 0.0 see the DIVSCALE section below stepfactor float 5.0 multiplicator for the number of atoms remodel integer 0 number of times to reconfigure the Gaussian Network settings dictionary {} additional settings for the underlying molecular mechanics methods. Takes the form of attribute-name:value pairs. Example: settings = { "NumberOfPrintDivisions" : -10, "GradientNorm" : 1E-3 } to set an attribute each in the Molecular Mechanics and Energy Minimization modules. With default settings, numsteps is set at a rounded number of atoms x stepfactor. For example, if there are 751 atoms, numsteps will be 5000, numstages 50 and initialhold 500. The outer radius is set at outratio x the inner radius and initialhold steps of energy minimization are out. This is followed by numsteps of energy minimization during which the outer radius ratio is reduced from an initial value of outratio to a final value of finalratio. This adjustment is carried out every numstages steps using a linear or non-linear profile depending on the value specified for divscale. AnnealMC The AnnealMC() function, also known as RBMC(), takes one to 14 arguments and it carries out a radius annealing as part of a Monte Carlo procedure using Rigid Body moves. This is the one function that makes use of the rigid bodies defined in the Partition Map file that went into the creation of the Model object. This function returns the transformation matrices. There should be one (if initialhold = 0) or two matrices for each rigid body. Argument Type Preset Value Description model Model The Emmental Model object numsweeps integer or None None total number of Monte Carlo sweeps, if None: set equal to stepfactor times the rounded number of atoms. numstages integer or None None number of steps between adjustment of the outer radius towards its final value, if None: numsweeps / 100, i.e., the outer radius will be adjusted in 100 stages. initialhold None or integer None number of initial Monte Carlo sweeps in which both the outer radius and temperature are held at fixed values, if None: numsweeps / 10 outratio float 5.0 initial value of the ratio between the outer and the inner radius of the holes. finalratio None or float None final value of the ratio between the outer and the inner radius of the holes, if None: set it to the ratio of the radius of the smallest sphere that encloses a voxel and the inner radius. maxTemp float 5000.0 highest formal temperature [K] review integer 0 if not 0, print statistics for this calculation divscale float 10.0 see the DIVSCALE section below mcmove float or tuple of floats 0.5 fraction of moves that are to be translation, the balance being rotations, thus legal values are 0 to 1 only, applied to all rigid units if single number given, if a tuple, each fraction will be applied to a corresponding rigid unit. move0 float 0.1 initial maximum translation [Å] turn0 float PI/180 initial maximum rotation angle [radian] stepfactor float 5.0 multiplicator for the number of atoms remodel integer 0 number of times to reconfigure the Gaussian Network settings dictionary {} additional settings for the underlying molecular mechanics methods. Takes the form of attribute-name:value pairs With default settings, numsweeps is set at a rounded number of atoms x stepfactor. For example, if there are 5101 atoms, numsweeps will be 25000, numstages 250 and initialhold 2500. The outer radius is set at outratio x the inner radius and initialhold steps of Monte Carlo is carried out at a formal temperature of maxTemp, using Rigid Body moves. This is followed by numsweeps of Monte Carlo during which the outer radius ratio is reduced from an initial value of outratio to a final value of finalratio. At the same time, the temperature is reduced from maxTemp to 0.1K. The radius adjustment is carried out every numstages steps using a linear or non-linear profile depending on the value specified for divscale. With the default settings, the radius is reduced very quickly indeed and the profile is almost that of a step function. The transformation matrices returned by this function is useful only if the model is coarse-grained. The transfomation matrices can then be applied to the all-atom model at the initial conformation to obtain a final conformation which is hopefully an optimal fit of the molecules into the density map. The TransformPDB() function in the Yup.Models.Emmental.Analyze module can take care of this chore. VLAT The VLAT() function, of historical interest only, takes one to seven arguments and it carries out a simulated annealing procedure using the Monte Carlo method with Rigid Body moves. This procedure tries to reproduce a similar procedure implemented in Yammp 1. As such, the outer radius ratio is set at a fixed value of 1.3960259829 throughout the process. This is not identical to the Yammp 1 procedure, the voxels are cubical in Yammp 1 while they are spherical in YUP. This function returns the transformation matrices, one (if initialhold = 0) or two per rigid unit. Argument Type Preset Value Description model Model The Emmental Model object numsweeps integer or None None total number of energy minimization steps, if None: set equal to stepfactor times the rounded number of atoms. numstages integer or None None number of steps between adjustment of the outer radius towards its final value, if None: numsweeps / 100, i.e., the outer radius will be adjusted in 100 stages. initialhold None or integer None number of initial Monte Carlo steps in which the temperature is held fixed at maxTemp, if None: numsweeps / 10 maxTemp float 100.0 highest formal temperature [K] review integer 0 if not 0: print the statistics from this simulation stepfactor float 5.0 multiplicator for the number of atoms With default settings, numsweeps is set at a rounded number of atoms x stepfactor. For example, if there are 301 atoms, numsweeps will be 1500, numstages 15 and initialhold 150. A conventional simulated annealing procedure is used. First, initialhold sweeps of Monte Carlo with Rigid Body moves are carried out at a fixed formal temperature of maxTemp. Then, numsweeps sweeps of Monte Carlo with Rigid Body moves are carried out, with the formal temperature dropping from an initial value of maxTemp to a final value of 0.1K. The temperature is adjusted on a linear profile every numstages sweep. The TransformPDB() function in the Yup.Models.Emmental.Analyze module can tbe used to apply the transformation matrices on an all-atom model in the original conformation to obtain a fitted conformation that is hopefully optimal. AnnealMD The AnnealMD() function, also known as Anneal(), takes one to 10 arguments and it carries out a radius annealing as part of an simulated annealing procedure based on the molecular dynamics method. Argument Type Preset Value Description model Model The Emmental Model object numsteps integer or None None total number of molecular dynamics annealing (cooling) steps, if None: set equal to stepfactor times the rounded number of atoms. numstages integer or None None number of steps between adjustment of the outer radius towards its final value, if None: numsteps / 100, i.e., the outer radius will be adjusted in 100 stages. initialhold None or integer None number of initial molecular dynamics steps in which the outer radius is held at a fixed value while the temperature is raised to maxTemp and then held at that temperature over four times this interval, if None: numsteps / 10 outratio float 5.0 initial value of the ratio between the outer and the inner radius of the holes. finalratio None or float None final value of the ratio between the outer and the inner radius of the holes, if None: set it to the ratio of the radius of the smallest sphere that encloses a voxel and the inner radius. maxTemp float 10.0 maximum temperature [K] divscale float 0 see the DIVSCALE section below stepfactor float 0.5 multiplicator for the number of atoms to yield the number of steps remodel integer 0 number of times to reconfigure the Gaussian Network settings dictionary {} additional settings for the underlying molecular mechanics methods. Takes the form of attribute-name:value pairs With default settings, numsteps is set at a rounded number of atoms x stepfactor. For example, if there are 45921 atoms, numsteps will be 46000, numstages 460 and initialhold 4600. The outer radius is set at outratio x the inner radius and 2 x initialhold steps of molecular dynamics is carried out during which the temperature is increased from a very low value to maxTemp, using a loosely coupled heat bath. The simulation continues for another 8 x initialhold steps with constant radius ratio and the temperature is held at maxTemp by periodic scaling of the velocities. This is followed by numsteps of molecular dynamics during which the outer radius ratio is reduced from an initial value of outratio to a final value of finalratio. This adjustment is carried out every numstages steps using a linear or non-linear profile depending on the value specified for divscale. At the same time, the temperature is reduced from maxTemp to a final value of 1K. The molecular dynamics simulations are carried out with a time step of 5 fs. It appears that we could comfortably use a time step as high as 10 fs or even higher since the temperature is so low. In fact, the temperature is kept just above 0K so that the atoms will have sufficient velocities to move. Other than keeping the molecule from freezing, the temperature is not the important annealing parameter. The annealing target is in fact the outer radius of the holes. The goal is to expose the atoms to a large number of holes at the start and then reduce the range of influence as the simulation optimizes the conformation of the molecule to the density map. At termination, each atom can only feel the influence of the closest holes. Minimize This function carries out a conventional energy minimization using the steepest descent procedure. The function takes on or two arguments. Argument Type Preset Value Description model Model the Emmental Model object numsteps integer 1000 number of steps DIVSCALE Many of the fitting methods offer an argument divscale that can be set to obtain a radius ratio profile. This is how the ratio of the outer to the inner radius of the SwissCheeseX term is to be reduced from an initial value R0, to a final value R1. The profiles obtained by setting divscale are: Value of divscale Radius Ratio Profile between -1-10-9 and 1+10-9 linear: the value of the ratio is reduced by the same amount at each step (green). > 1+10-9 non-linear: at each step the difference between the prevailing value and the target value is reduced by dividing by divscale. The radius ratio is reduced quickly in the early steps (red). < -1-10-9 non-linear: at each step the difference between the prevailing value and the target value is reduced by multiplying by -divscale. The radius ratio is reduced slowly in the early steps (blue). Whichever profile is used, the final value of the ratio is always obtained on or before the last step, i.e., there is no chance of missing the target. EXAMPLES In the following, all the commands are typed into a Python interpreter. from Yup.Models.Emmental.Calculate import AnnealMC, AnnealMD AnnealMD( M2, outratio = 3.25 ) T = AnnealMC( M1, review = 1 ) In the above examples, the model M2, which you will remember, is an all-atom model, is refined using a molecular dynamics-based simulated annealing procedure. The outer to inner radii ratio is set at 3.25 since with default value is too high for a large model. Following that the model M1, which is a coarse-grained model is refined using a Monte Carlo-based simulated annealing procedure and we elect to print the statistics from the simulation. Note that the function returns the transformation matrices which we assign to a symbol T for later use. This module defines a private class _hegemon, that has two methods, one for a linear radius profile and the other for a non-linear radius profile. Then, _hegemon is mixed-in with a molecular mechanics class to create a customized class. For example, the customized molecular dynamics class _motor is based on _hegemon and the Motors class from the Yup.Methods.MolDynam module. In this way, we modify the standard molecular dynamics routine, which has such steps as integrating the equations of motion, updating the nonbond lists, printing results periodically, and so on. The modification that we make is to insert a task to be carried out periodically, before the integration step, the reduction of the outer radius and we select at the start whether to do this linearly or non-linearly. Similarly, _hegemon and Casino (from Yup.Methods.MonteCarlo) are the parents of the customized monte carlo class _casino. In the non-linear annealing, the outer radius target is set such that the desired final value is achieved in the specified number of steps. Analyze Utilities