Class: MDArena

Description

Overview

The class MDArena provides access to the MM/MD runtime information for a Molecule. To run a MM/MD calculation from script, the following steps should be followed.

Obtain the MDArena object by Molecule#md_arena.
Initialize the MM/MD runtime by MDArena#prepare. 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.
Run an energy minimization by MDArena#minimize, or a simulation by MDArena#run.

MDArena attributes

The MM/MD calculation uses many setting parameters and runtime information, which are accessible as attributes of MDArena. The available attributes are listed below:

name	value type	description
timestep	Float	The timestep (in femtosecond) for solving the Newtonian equation of motion. Default: 1 fs.
cutoff	Float	The cutoff distance (in Å) for van der Waals interaction. Default: 9.0 Å.
electro_cutoff	Float	The cutoff distance (in Å) for electrostatic interaction. Default: 9.0 Å.
pairlist_distance	Float	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 `(pairlist_distance - cutoff)` or `(pairlist_distance - electro_cutoff)`. The recommended value is `cutoff + 1.0` or `electro_cutoff + 1.0`, whichever is larger. Default: 10.0 Å.
switch_distance	Float	The switching distance (in Å) for van der Waals interaction; between switch_distance and cutoff, the van der Waals potential decreases linearly to zero. Default: 8.0 Å.
temperature	Float	The target temperature (in Kelvin). Default: 300.0 K.
transient_temperature	Float	The transient temperature at the last MD step (in Kelvin). Read only.
average_temperature	Float	The average temperature from the beginning of the MD run (in Kelvin). Read only.
andersen_freq	Integer	The frequency to perform Andersen thermostat. Default: 50.
andersen_coupling	Float	The coupling constant for Andersen thermostat. Default: 0.1.
random_seed	Integer	The random seed. Default: 0 (new seed is generated at every initialization).
dielectric	Float	The dielectric constant of the media. Default: 1.0.
gradient_convergence	Float	The gradient threshold for terminating minimization. Default: 1e-6.
coordinate_convergence	Float	The coordinate threshold for terminating minimization. Default: 1e-8.
use_xplor_shift	Integer	If non-zero, use X-PLOR type shift for the electrostatic potential. Default: 1.
scale14_vdw	Float	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.
scale14_elect	Float	Scale factor for the electrostatic potentials for the 1-4 atom pair. Default: 0.83.
relocate_center	Integer	If non-zero, then relocate the whole system so that the center of mass does not move. Default: 0.
step	Integer	The current step. Read only.
coord_frame	Integer	The last frame number created by this calculation. Read only.
coord_file	String	The output file name for coordinates. The file is in the "crd" format. Default: nil (no output)
vel_file	String	The output file name for velocities. The file is in the "crd" format. Default: nil (no output)
force_file	String	The output file name for force. The file is in the "crd" format. Default: nil (no output)
log_file	String	The output file name for the log. Default: nil (no output)
debug_file	String	The output file name for the debug information. Default: nil (no output)
coord_output_freq	Integer	Output the coordinates every this step. Default: 10.
energy_output_freq	Integer	Output the energies every this step to the log file. Default: 10.
debug_output_level	Integer	Set the verbosity of the debug information. Default: 0.
use_graphite	Integer	If non-zero, an infinite array of graphite carbons are assumed in the xy plane. Default: 0.
alchemical_lambda	Float	When the alchemical transformation is turned on, this parameter defines the population of the appearing group.
alchemical_delta_lambda	Float	When the alchemical transformation is turned on, this parameter defines the increment width of the lambda parameter. Default: 0.1.
alchemical_energy	Float	When the alchemical transformation is turned on, this parameter gives the energy difference for incremental change of the lambda parameter. Read only.
minimize_cell	Boolean	Flag to determine whether the unit cell should be minimized. Default: false.
use_ewald	Integer	If 1, the Particle Mesh Ewald technique is used. Default: 0.
ewald_beta	Float	The beta parameter for the PME calculation. Default: 0.25
ewald_order	Integer	The spline order for the PME calculation. Default: 8
ewald_freq	Integer	The frequency to perform the PME calculation. Default: 2

Public Instance methods

self[attr]
self[attr] = value

Get/set the attribute value. The attribute values also can be accessed by self.attribute_name and self.attribute_name = value. See the MDArena attributes section for the list of available attributes.

angle_par(idx) → ParameterRef

Returns a MM/MD parameter record that is used for the idx-th angle.

bond_par(idx) → ParameterRef

Returns a MM/MD parameter record that is used for the idx-th bond.

dihedral_par(idx) → ParameterRef

Returns a MM/MD parameter record that is used for the idx-th dihedral.

energies → [total, bond, angle, dihedral, improper, vdw, electrostatic, auxiliary, surface, kinetic, net]

Get the energies at the last step of the MM/MD calculation. The unit is kcal/mol.

get_alchemical_perturbation → [vanish_group, appear_group] or nil

Get the vanishing and appearing atom groups for alchemical perturbation. If alchemical perturbation is disabled, returns nil (not [nil, nil]).

get_external_force(index) → Vector3D or nil

Get the current external force for the atom. If the external force is not set, nil is returned.

improper_par(idx) → ParameterRef

Returns a MM/MD parameter record that is used for the idx-th improper torsion.

init_velocities(temperature = nil) → self

Give random velocities to the atoms according to the Boltzmann distribution. If temperature is given, it is also set as the 'temperature' attribute.

keys → Array

Returns an array of attribute keys.

minimize(n) → self
minimize(n) { ... } → self

Minimize the MM energy for n steps. If a block is given, it is executed when minimization is complete.

prepare(check_only = false) → self or nil

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 "Undo support" of the Molecule document).

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 check_only argument is true, then self is returned at this point. Otherwise, the runtime fields for MM/MD calculation are initialized and self is returned.

run(n) → self

Run the MD simulation for n steps.

scale_velocities(temperature = nil) → self

Scale the current velocities of the atoms according to the Boltzmann distribution. If temperature is given, it is also set as the 'temperature' attribute.

set_alchemical_perturbation(vanish_group, appear_group) → [vanish_group, appear_group]

Set the vanishing and appearing atom groups for alchemical perturbation. To disable alchemical perturbation, give nil for the both groups.

set_external_forces(array) → self

Set external forces. Array should be an array of objects that can be converted to Vector3D, or nil to remove all external forces.

to_hash → Hash

Returns a (frozen) hash that contains the current values of all attributes.

vdw_par(idx) → ParameterRef

Returns a MM/MD parameter record that is used for the van der Waals parameter of the idx-th atom.