The Model class manages the components of a molecular model: the Root AtomMap, the Energy list (Potential), the AtomVectors for coordinates, gradients, velocities and inverse mass. How to Use Normally, a Force Field Assembler (FFA) will create an instance of the Model class and will fill the class with Map (using the add_Map() method), Energy (using the add_Energy() method and then populate this component) and possibly Coordinates (using the add_Coordinates() method). Then the FFA returns the partially filled object to the caller. The user may have to fill the parts that the FFA had ignored. For example, to register the Coordinates component (if the FFA had not done so) or to fill the Coordinates AtomVector with proper values (by reading an AVF or generating the coordinates). Finally the user would pass the Model to a molecular mechanics method (MMM) for the simulation. The MMM would query this object for the parts that it need for the calculation: the various AtomVectors: Coordinates, Gradients, Velocities and InverseMass. Then the MMM will call the compile(), update() and evaluate() methods to complete its task. Housekeeping This class takes care of some housekeeping functions. For example, it makes sure that all the required components of a molecular mechanics (MM) simulation are present before attempting the calculation and will fill in the missing components when it is possible to do so. The Energy modules must be compiled before evaluation of the energy and first derivatives. This modules takes care of the initial compilation. The first derivatives are accumulated into the Gradients AtomVector by each of the energy objects. Therefore, this vector must be empty at the start of each evaluation. This module takes care of this and it also keeps a count of the number of times the energy function is evaluated. Location The Model module is located in Yup.Taro. Data Attributes All the data attributes are read-only. These attributes should not be assigned new values. If you do assign to these attributes the real values will be "covered" by your definition and further use of the object will likely fail. To recover from this stupidity, delete the attribute. Data Attribute Description Map The Root AtomMap registered by the add_Map() method. This attribute does not exist until an AtomMap is registered. Energy The Potential object registered by the add_Energy() method. This attribute does not exist until a Potential object is registered. Coordinates The AtomVector object registered by the add_Coordinates() method. This attribute does not exist until an AtomVector is registered. Gradients The Gradients AtomVector object. This is first created when all three of the objects represented by the Map, Energy and Coordinates attributes have been registered. Until then, this attribute does not exist. Velocities The Velocities AtomVector object. This is first created when both of the objects represented by the Map and Coordinates attributes have been registered. Until then, this attribute does not exist. InverseMass The Inverse Mass AtomVector object. This is first created when the object represented by the Map attribute has been registered. Until then, the InverseMass attribute does not exist. Other Attributes Any other data attribute can be attached to the Model but the following are semi-official: Data Attribute Description draw Used by the MakeGraph routines to generate molecular graphic objects. LIMIT Used by the molecular simulation methods to confine the calculations to a contiguous slice of the model. Many model types attach an attribute named after the type so that it can be easily identified. If a function  works only with a specific model type, it can easily check for the existence of the self-named attribute before proceeding. Methods There are 10 methods. Six are discussed in this section. The remaining four are designed for Monte Carlo simulation and are discussed below. The add_Map() method registers the given object as the Map attribute. Although any kind of AtomMap is accepted, anything other than the Root AtomMap will cause problems later on. This method must be called exactly once. Method Name Number of Arguments Return Value add_Map 1 None Keyword Argument Preset Value amap Root AtomMap - The add_Energy() method registers the given object as the Energy attribute. The argument must be an instance of the Potential class. This method must be called exactly once. Method Name Number of Arguments Return Value add_Energy 1 None Keyword Argument Preset Value ene Potential object - The add_Coordinates() method registers the given object as the Coordinates attribute. The specified argument must be an AtomVector. Each time a new Coordinates AtomVector is registered, new Gradients, Velocities and InverseMass are created as well. Method Name Number of Arguments Return Value add_Coordinates 1 None Keyword Argument Preset Value crd AtomVector object - The evaluate() method applies the evaluate() method on each of the objects in the Energy list, and returns the sum of the result which is the total energy. Both arguments are optional. If the Map, Energy and Coordinates attributes have not all been defined, an exception is raised. The Gradients AtomVector is set to zero values before the evaluate() method is applied on the individual objects. This ensures that Gradients contain only the total of the first derivatives for the current Coordinates. Finally, numcalls is incremented by one. Method Name Number of Arguments Return Value evaluate 2 floating point Keyword Argument Preset Value coordinates Optional AtomVector object None gradients Optional AtomVector object None The update() method applies the update() method on each of the objects in the Energy list. The Map, Energy and Coordinates attributes must all be defined before this method is called, or an exception is raised. Method Name Number of Arguments Return Value update 0 None The compile() method applies the compile() method, with an empty argument list, on each of the objects in the Energy list. The Map, Energy and Coordinates attributes must all be defined before this method is called, or an exception is raised. Method Name Number of Arguments Return Value compile 0 None Monte Carlo Methods The four remaining methods are designed for Monte Carlo (MC) simulations are are discussed here (will open in a separate window). Most of these methods are called very frequently in MC simulations. Therefore, they carry out very few error checks. The methods have to be called in the proper order. A MC method object is created by calling mcprep() with a non-empty list of move units. A move unit is a group of atoms whose coordinates form a contiguous block. The MC object can be created only when the Model object has most of its components; the crucial step is the creation of the Coordinates and a call to the compile() method. The MC object is refreshed whenever the nonbond lists are updated (using the update() method). Each MC simulation must be initialized, by calling mcprep() with no arguments. Then, the simulation will consist of selecting a move unit at random, transforming the coordinates of the atoms that make up the selected unit, calculating the change in energy caused by the trial move, making a decision on whether to accept or reject the move and to act on the decision. Most of these actions are taken elsewhere. The mcmove() method calculates and returns the change in energy caused by a trial move. The actual transform is accomplished elsewhere; mcmove() assumes that the coordinates have been transformed. The Model object is indifferent to the rejection of a trial move. However, if a move is accepted, the Model object needs to update its energy table; this is accomplished with a call to the mcpass() method. Finally, the method mceval() returns the total energy. The MC object is deleted if the compile() method is called after the creation of the former. The MC object can be directly deleted by calling mcprep() with an empty list of move units. In either case, no further MC simulations can be carried out.