Documents/src/molby_rb/MDArena.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html
   3      PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8   <title>Class: MDArena</title>
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10   <meta http-equiv="Content-Script-Type" content="text/javascript" />
  11   <link rel="stylesheet" href="rdoc-style.css" type="text/css" media="screen" />
  12 </head>
  13 <body>
  14
  15 <div id="navi">
  16 <a href="../index.html">[Molby Document Home]</a>
  17 <a href="../ruby_ref.html">[Contents]</a>
  18 </div>
  19
  20 <div id="classHeader">
  21 <table class="header-table">
  22 <tr>
  23 <td><strong>Class:</strong></td>
  24 <td class="class-name-in-header">MDArena</td>
  25 </tr>
  26 <tr>
  27 <td><strong>Parent:</strong></td>
  28 <td><a href="Object.html">Object</a></td>
  29 </tr>
  30 </table>
  31 </div>
  32
  33 <div id="section">
  34 <h3 class="section-bar">Description</h3>
  35 <a name="description-overview"></a>
  36 <h4>Overview</h4>
  37 <p>
  38 The class <a href="MDArena.html">MDArena</a> provides access to the MM/MD runtime information for a <a href="Molecule.html">Molecule</a>. To run a MM/MD calculation from script, the following steps should be followed.
  39 </p>
  40 <ul>
  41 <li>Obtain the <a href="MDArena.html">MDArena</a> object by <a href="Molecule.html#M000313">Molecule#md_arena</a>.</li>
  42 <li>Initialize the MM/MD runtime by <a href="MDArena.html#M000046">MDArena#prepare</a>. If it raises exception or returns nil, some of the settings need modification (providing missing parameters, etc.) before the MM/MD calculation can be run.</li>
  43 <li>Run an energy minimization by <a href="MDArena.html#M000045">MDArena#minimize</a>, or a simulation by <a href="MDArena.html#M000044">MDArena#run</a>.</li>
  44 </ul>
  45 <a name="description-attributes"></a>
  46 <h4>MDArena attributes</h4>
  47 <p>
  48 The MM/MD calculation uses many setting parameters and runtime information, which are accessible as attributes of <a href="MDArena.html">MDArena</a>. The available attributes are listed below:
  49 </p>
  50 <table border="1" cellspacing="0">
  51 <tr><th>name</th><th>value type</th><th>description</th></tr>
  52 <tr><td>timestep</td><td>Float</td><td>The timestep (in femtosecond) for solving the Newtonian equation of motion. Default: 1 fs.</td></tr>
  53 <tr><td>cutoff</td><td>Float</td><td>The cutoff distance (in Å) for van der Waals interaction. Default: 9.0 Å.</td></tr>
  54 <tr><td>electro_cutoff</td><td>Float</td><td>The cutoff distance (in Å) for electrostatic interaction. Default: 9.0 Å.</td></tr>
  55 <tr><td>pairlist_distance</td><td>Float</td><td>The threshold distance for making the pairlist table. The pairlist table records the interatomic distances, and is updated when the maximum displacement of any atom exceeds <code>(pairlist_distance - cutoff)</code> or <code>(pairlist_distance - electro_cutoff)</code>. The recommended value is <code>cutoff + 1.0</code> or <code>electro_cutoff + 1.0</code>, whichever is larger. Default: 10.0 Å.</td></tr>
  56 <tr><td>temperature</td><td>Float</td><td>The target temperature (in Kelvin). Default: 300.0 K.</td></tr>
  57 <tr><td>transient_temperature</td><td>Float</td><td>The transient temperature at the last MD step (in Kelvin). Read only.</td></tr>
  58 <tr><td>average_temperature</td><td>Float</td><td>The average temperature from the beginning of the MD run (in Kelvin). Read only.</td></tr>
  59 <tr><td>andersen_freq</td><td>Integer</td><td>The frequency to perform Andersen thermostat. Default: 50.</td></tr>
  60 <tr><td>andersen_coupling</td><td>Float</td><td>The coupling constant for Andersen thermostat. Default: 0.1.</td></tr>
  61 <tr><td>random_seed</td><td>Integer</td><td>The random seed. Default: 0 (new seed is generated at every initialization).</td></tr>
  62 <tr><td>dielectric</td><td>Float</td><td>The dielectric constant of the media. Default: 1.0.</td></tr>
  63 <tr><td>gradient_convergence</td><td>Float</td><td>The gradient threshold for terminating minimization. Default: 1e-6.</td></tr>
  64 <tr><td>coordinate_convergence</td><td>Float</td><td>The coordinate threshold for terminating minimization. Default: 1e-8.</td></tr>
  65 <tr><td>use_xplor_shift</td><td>Integer</td><td>If non-zero, use X-PLOR type shift for the electrostatic potential. Default: 1.</td></tr>
  66 <tr><td>scale14_vdw</td><td>Float</td><td>Scale factor for the van der Waals potentials for the 1-4 atom pair (i.e. the pair of atoms that are connected through 3 bonds). Default: 0.5.</td></tr>
  67 <tr><td>scale14_elect</td><td>Float</td><td>Scale factor for the electrostatic potentials for the 1-4 atom pair. Default: 0.83.</td></tr>
  68 <tr><td>relocate_center</td><td>Integer</td><td>If non-zero, then relocate the whole system so that the center of mass does not move. Default: 0.</td></tr>
  69 <tr><td>step</td><td>Integer</td><td>The current step. Read only.</td></tr>
  70 <tr><td>coord_frame</td><td>Integer</td><td>The last frame number created by this calculation. Read only.</td></tr>
  71 <tr><td>coord_file</td><td>String</td><td>The output file name for coordinates. The file is in the "crd" format. Default: nil (no output)</td></tr>
  72 <tr><td>vel_file</td><td>String</td><td>The output file name for velocities. The file is in the "crd" format. Default: nil (no output)</td></tr>
  73 <tr><td>force_file</td><td>String</td><td>The output file name for force. The file is in the "crd" format. Default: nil (no output)</td></tr>
  74 <tr><td>log_file</td><td>String</td><td>The output file name for the log. Default: nil (no output)</td></tr>
  75 <tr><td>debug_file</td><td>String</td><td>The output file name for the debug information. Default: nil (no output)</td></tr>
  76 <tr><td>coord_output_freq</td><td>Integer</td><td>Output the coordinates every this step. Default: 10.</td></tr>
  77 <tr><td>energy_output_freq</td><td>Integer</td><td>Output the energies every this step to the log file. Default: 10.</td></tr>
  78 <tr><td>debug_output_level</td><td>Integer</td><td>Set the verbosity of the debug information. Default: 0.</td></tr>
  79 </table>
  80 </div>
  81
  82 <div id="section">
  83
  84 <div id="methods">
  85 <h3 class="section-bar">Public Instance methods</h3>
  86
  87 <div id="method-M000048" class="method-detail">
  88 <a name="M000048"></a>
  89 <div class="method-heading">
  90 <span class="method-name">self[attr]<br />
  91 self[attr] = value
  92 </span>
  93 </div>
  94 <div class="method-description">
  95 <p>
  96 Get/set the attribute value. The attribute values also can be accessed by <code>self.attribute_name</code> and <code>self.attribute_name = value</code>. See the <a href="#description-attributes">MDArena attributes</a> section for the list of available attributes.
  97 </p>
  98 </div>
  99 </div>
 100
 101 <div id="method-M000047" class="method-detail">
 102 <a name="M000047"></a>
 103 <div class="method-heading">
 104 <span class="method-name">energies &rarr; [total, bond, angle, dihedral, improper, vdw, electrostatic, auxiliary, surface, kinetic, net]<br />
 105 </span>
 106 </div>
 107 <div class="method-description">
 108 <p>
 109 Get the <a href="MDArena.html#M000047">energies</a> at the last step of the MM/MD calculation. The unit is kcal/mol.
 110 </p>
 111 </div>
 112 </div>
 113
 114 <div id="method-M000047" class="method-detail">
 115 <a name="get_external_force"></a>
 116 <div class="method-heading">
 117 <span class="method-name">get_external_force(index) &rarr; <a href="Vector3D.html">Vector3D</a> or nil</span>
 118 </div>
 119 <div class="method-description">
 120 <p>
 121 Get the current external force for the atom. If the external force is not set, nil is returned.
 122 </p>
 123 </div>
 124 </div>
 125
 126 <div id="method-init_velocities" class="method-detail">
 127 <a name="init_velocities"></a>
 128 <div class="method-heading">
 129 <span class="method-name">init_velocities(temperature = nil) &rarr; self<br />
 130 </span>
 131 </div>
 132 <div class="method-description">
 133 <p>
 134 Give random velocities to the atoms according to the Boltzmann distribution. If temperature is given, it is also set as the 'temperature' attribute.
 135 </p>
 136 </div>
 137 </div>
 138
 139 <div id="method-M000050" class="method-detail">
 140 <a name="keys"></a>
 141 <div class="method-heading">
 142 <span class="method-name">keys &rarr; Array<br />
 143 </span>
 144 </div>
 145 <div class="method-description">
 146 <p>
 147 Returns an array of attribute keys.
 148 </p>
 149 </div>
 150 </div>
 151
 152 <div id="method-M000045" class="method-detail">
 153 <a name="M000045"></a>
 154 <div class="method-heading">
 155 <span class="method-name">minimize(n)       &rarr; self<br />
 156 minimize(n) { ... } &rarr; self<br />
 157 </span>
 158 </div>
 159 <div class="method-description">
 160 <p>
 161 Minimize the MM energy for n steps. If a block is given, it is executed when
 162 minimization is complete.
 163 </p>
 164 </div>
 165 </div>
 166
 167 <div id="method-M000046" class="method-detail">
 168 <a name="M000046"></a>
 169 <div class="method-heading">
 170 <span class="method-name">prepare(check_only = false)         &rarr; self or nil<br />
 171 </span>
 172 </div>
 173 <div class="method-description">
 174 <p>
 175 Prepare for the MD calculation. The angles and dihedrals may be rebuilt so that they are consistent with the bond information, and the impropers may be added where the corresponding improper parameters are defined (even if the force constant is zero). These result in the modification of the angle/dihedral/improper tables of the Molecule, which are undoable (see "<a href="Molecule.html#description-undo-support">Undo support</a>" of the Molecule document).
 176 </p>
 177 <p>
 178 After the above rebuild is done, the MM parameters are looked for. If any necessary parameters are missing, then nil is returned at this point. If all parameters are found, and if the <code>check_only</code> argument is true, then self is returned at this point. Otherwise, the runtime fields for MM/MD calculation are initialized and self is returned.
 179 </p>
 180 </div>
 181 </div>
 182
 183 <div id="method-M000044" class="method-detail">
 184 <a name="M000044"></a>
 185 <div class="method-heading">
 186 <span class="method-name">run(n)       &rarr; self<br />
 187 </span>
 188 </div>
 189 <div class="method-description">
 190 <p>
 191 Run the MD simulation for n steps.
 192 </p>
 193 </div>
 194 </div>
 195
 196 <div id="method-scale_velocities" class="method-detail">
 197 <a name="scale_velocities"></a>
 198 <div class="method-heading">
 199 <span class="method-name">scale_velocities(temperature = nil) &rarr; self<br />
 200 </span>
 201 </div>
 202 <div class="method-description">
 203 <p>
 204 Scale the current velocities of the atoms according to the Boltzmann distribution. If temperature is given, it is also set as the 'temperature' attribute.
 205 </p>
 206 </div>
 207 </div>
 208
 209 <div id="method-M000047" class="method-detail">
 210 <a name="set_external_forces"></a>
 211 <div class="method-heading">
 212 <span class="method-name">set_external_forces(array) &rarr; self</span>
 213 </div>
 214 <div class="method-description">
 215 <p>
 216 Set external forces. Array should be an array of objects that can be converted to <a href="Vector3D.html">Vector3D</a>, or nil to remove all external forces.
 217 </p>
 218 </div>
 219 </div>
 220
 221 <div id="method-M000050" class="method-detail">
 222 <a name="M000050"></a>
 223 <div class="method-heading">
 224 <span class="method-name">to_hash &rarr; Hash<br />
 225 </span>
 226 </div>
 227 <div class="method-description">
 228 <p>
 229 Returns a (frozen) hash that contains the current values of all attributes.
 230 </p>
 231 </div>
 232 </div>
 233
 234 </div>
 235
 236 </div>
 237
 238 </body>
 239 </html>