[Molby Document Home] [Contents]

Class: | Molecule
Parent: | Object

### Description

#### Overview

The class Molecule is the principal data structure in Molby. It contains the list of atoms, bonds, angles, dihedrals, and impropers. It may also contain optional information such as a unit cell, symmetry operations, multiple frames, electrostatic potentials, quantum chemistry information (basis sets and MO coefficients), MM/MD parameters (see class Parameter), and MM/MD runtime information (see class MDArena).

#### Documents and Molecule objects

Molecule objects can be obtained from the documents; examples are the return values of Molecule#current and Molecule[name]. However, not all Molecule objects necessarily have the associated documents. Some methods of Molecule generates a new Molecule object that has no associated document (e.g. Molecule#new, Molecule#dup, Molecule#extract). Such Molecule objects are useful for keeping partial structures until model-building is complete.

#### AtomRef

Atoms are the most important component in Molecule. For efficiency reasons, the internal representation of atoms is a flat array, not a collection of "Atom" objects. Consequently, there is no "Atom" object in Molby; instead, an atom is represented by the AtomRef object, which "points" to a particular atom via a pointer to Molecule and an index.

#### Atom index

The atom index in Molby is 0-based, unlike the 1-based index found in many chemical files. In addition, there is a convenient way to specify an atom via its name and (optionally) the residue name and residue number. Thus, if an atom has a name "CA" and belongs to a residue number 1 named "RES", then the atom can be specified by "CA", "1:CA", "RES:CA", or "RES.1:CA". If the description matches more than two atoms, it specifies the atom with the lowest index. Such description is acceptable in such methods like MolEnumerable#[], Molecule#atom_group, etc.

#### MolEnumerable

As described above, the components in Molecule such as atoms, bonds, etc. are not represented by Array objects of Ruby. Nevertheless, it is often convenient if we can treat the collection of these substances as a single Enumerable object. The class MolEnumerable does this job, and allows to access the individual substances in an Array-like manner, e.g. `mol.atoms[n]` (mol.atoms is a MolEnumerable object).

#### Atom group

Many methods of Molecule take a "group" argument, which means a group of atoms. A group is represented by an IntGroup object, which is a collection of non-negative integers.

#### Undo support

Many methods of Molecule are described as "undoable". This means, when such methods are invoked for a Molecule that has an associated document, an undo operation is automatically registered to the document.

#### Graphic objects

(New in 0.6.2) Some Ruby methods allow you to handle graphic objects that are displayed in the same view as the molecule. The methods include create_graphic, remove_graphic, ngraphics, set_graphic_point, set_graphic_color, show_graphic, and hide_graphic.

### Public Class methods

Molecule[] → Molecule
Molecule[n] → Molecule
Molecule[name] → Molecule
Molecule[name, k] → Molecule
Molecule[regex] → Molecule
Molecule[regex, k] → Molecule

Molecule[] is equivalent to Molecule.current. Molecule[n] (n is an integer) is equivalent to Molecule.list[n]. Molecule[name] gives the first document (in the order of creation time) that has the given name. If a second argument (k) is given, the k-th document that has the given name is returned. Molecule[regex] gives the first document (in the order of creation time) that has a name matching the regular expression. If a second argument (k) is given, the k-th document that has a name matching the regex is returned.

calc_angle(v1, v2, v3) → Float

Calculate the angle defined by three vectors. The result is in degree.

See Also: Molecule#calc_angle (Instance Method)

calc_bond(v1, v2) → Float

Calculate the bond length defined by two vectors.

See Also: Molecule#calc_bond (Instance Method)

calc_dihedral(v1, v2, v3, v4) → Float

Calculate the dihedral angle defined by four vectors. The result is in degree.

See Also: Molecule#calc_dihedral (Instance Method)

current → Molecule

Get the currently "active" molecule.

from_formula(str, resname = nil) → (new) Molecule

Convert a string (like "CH2OCH3") to a molecule.

list → Array of Molecule

Get the list of molecules associated to the documents, in the order of creation time of the document. If no document is open, returns an empry array.

error_message → String
self.error_message = String
set_error_message(String)

Get/set the error_message from the last load/save method. Nil means no error.

new → (new) Molecule
new(file, *args) → (new) Molecule

Create a new molecule. If any arguments are given, call molload method with the same arguments. The created molecule has no associated document window.

See Also: Molecule#open, which opens the molecule as a document (i.e. with associated window).

open → (new) Molecule
open(file) → (new) Molecule

Open a molecule from file as a document. If file is not given, an untitled document is created.

See Also: Molecule#new, which creates a new Molecule object but does not open as a document (i.e. no associated window is opened).

ordered_list → Array of Molecule

Get the list of molecules which are opened as documents, in the order of front-to-back ordering of the associated window. If no document is open, returns an empry array.

### Public Instance methods

add(molecule2) → self

Combine two molecules. The residue numbers of the newly added atoms may be renumbered to avoid conflicts. This operation is undoable.

add_angle(n1, n2, n3) → self

Add angle n1-n2-n3. Returns self. Usually, angles are automatically added when a bond is created, so it is rarely necessary to use this method explicitly. This operation is undoable.

See Also: Molecule#create_bond

add_atom(name, atom_type = "c3", element = "C", bond = nil, base1 = nil, angle = nil, base2 = nil, dihed = nil, base3 = nil) -> AtomRef

Add a new atom. The arguments bond, base1, angle, base2, dihed, and base3 defines the position of the new atom in the Z-matrix style. (Note: angle and dihed should be given in degree, not in radian). If bond/base1 are specified, a new bond is also created between the new atom and base1. If bond/base1 are specified but angle/base2 are not, then the direction of the new bond is assumed as the most distant direction from the existing bonds. Returns the reference to the new atom. This operation is undoable.

See Also: Molecule#create_atom

add_dihedral(n1, n2, n3, n4) → self

Add dihedral n1-n2-n3-n4. Returns self. Usually, dihedrals are automatically added when a bond is created, so it is rarely necessary to use this method explicitly. This operation is undoable.

See Also: Molecule#create_bond

add_gaussian_orbital_shell(sym, nprims, atom_index) → self

Only used internally. Add a gaussian orbital shell with symmetry code, number of primitives, and the corresponding atom index. Symmetry code: 0, S-type; 1, P-type; -1, SP-type; 2, D-type; -2, D5-type.

add_gaussian_primitive_coefficients(exponent, contraction, contraction_sp) → self

Only used internally. Add a gaussian primitive coefficients.

add_hydrogen(idx, atype, bond = 1.07, anum = 1)

Add missing hydrogen (or other atom) according to the given geometry type. Atype is a String, which is one of the following: "td" (tetrahedral), "tr" (trigonal), "py" (pyramidal, like amine nitrogen), "li" (linear). This operation is undoable.

add_improper(n1, n2, n3, n4) → self

Add dihedral n1-n2-n3-n4. Returns self. Unlike angles and dihedrals, impropers are not automatically added when new bonds are created, so this method is more useful than the angle/dihedral counterpart. This operation is undoable.

add_symmetry(Transform) → Integer

Add a new symmetry operation. If no symmetry operation is defined and the given argument is not an identity transform, then an identity transform is added before the given transform is added. Returns the new total number of symmetry operations. This operation is undoable.

all → IntGroup

Returns IntGroup[0..natoms-1], which represents "all atoms in the molecule".

amend_by_symmetry(group = nil) → IntGroup

Replace the symmetry-expanded atoms so that the positions are correctly related to those of the base atoms. If an atom group is given as the argument, only those atoms whose base atoms are in the groups are processed. Returns the group of processed atoms.

angle_par(idx) → ParameterRef
bond_par(idx) → ParameterRef
dihedral_par(idx) → ParameterRef
improper_par(idx) → ParameterRef
vdw_par(idx) → ParameterRef

These methods are now obsolete. Use the MDArena methods with the same name.

See Also: MDArena#angle_par, MDArena#bond_par, MDArena#dihedral_par, MDArena#improper_par, MDArena#vdw_par

angles → MolEnumerable

Returns a MolEnumerable object representing the array of angles. An angle n1-n2-n3 is represented [n1, n2, n3], where n1, n2, n3 are the atom indices.

See Also: Molecule#nangles

assign_bond_order(idx, d1) → self
assign_bond_orders(group, [d1, d2, ...]) → self

Assign bond order. In the first form, the bond order of the idx-th bond is set to d1 (a Float value). In the second form, the bond orders at the indices in the group are set to d1, d2, etc. At present, the bond orders are only used in UFF parameter guess, and not in the MM/MD calculations. (This may change in the future) This operation is undoable.

assign_residue(group, res) → self

Assign the specified atoms (as IntGroup) to have the given residue. res can either be an integer, "resname" or "resname.resno". When the residue number is not specified, the residue number of the first atom in the group is used. This operation is undoable.

atom_group → IntGroup
atom_group {|aref| ...} → IntGroup
atom_group(arg1, arg2, ...) → IntGroup
atom_group(arg1, arg2, ...) {|aref| ...} → IntGroup

Specify a group of atoms. If no arguments are given, IntGroup[0..natoms-1] is the result. If arguments are given, then the atoms reprensented by the arguments are added to the group. For a conversion of a string to an atom index, see the description of Molecule#atom_index.

If a block is given, it is evaluated with an AtomRef (not atom index integers) representing each atom, and the atoms are removed from the result if the block returns false.

See Also: Molecule#all

atom_index(val) → Integer

Returns the atom index represented by val. Val can be either a non-negative integer (directly representing the atom index), a negative integer (representing natoms - val), a string of type "resname.resid:name" or "resname:name" or "resid:name" or "name", where resname, resid, name are the residue name, residue id, and atom name, respectively. If val is a string and multiple atoms match the description, the atom with the lowest index is returned.

atoms → MolEnumerable

Returns a MolEnumerable object representing the array of atoms.

See Also: Molecule#natoms

bond_exist?(idx1, idx2) → bool

Returns true if bond exists between atoms idx1 and idx2, otherwise returns false. Imaginary bonds between a pi-anchor and member atoms are not considered.

bonds → MolEnumerable

Returns a MolEnumerable object representing the array of bonds. A bond n1-n2 is represented by an array [n1, n2], where n1 and n2 are the atom index integers.

See Also: Molecule#nbonds

bonds_on_border(group = selection) → [[na1, nb1], [na2, nb2], ...]

Returns an array of bonds that connect atoms in the group and atoms out of the group. The first atom in the bond always belongs to the group. If no such bonds are present, an empty array is returned.

bounds(group = nil) → [min, max]

Calculate the boundary. The return value is an array of two Vector3D objects.

See Also: Molecule#min, Molecule#max

box → [avec, bvec, cvec, origin, flags]

Get the unit cell information in the form of a periodic bounding box. Avec, bvec, cvec, origin are Vector3D objects, and flags is a 3-member array of Integers which define whether the system is periodic along the axis. If no unit cell is defined, nil is returned.

See Also: Molecule#box=, Molecule#cell, Molecule#cell=

self.box = [avec, bvec, cvec, origin = [0, 0, 0], flags = [1, 1, 1], convert_coord = nil]
self.box = [d, origin = [0, 0, 0]]
self.box = nil
set_box(avec, bvec, cvec, origin = [0, 0, 0], flags = [1, 1, 1], convert_coord = nil)
set_box(d, origin = [0, 0, 0])
set_box

Set the unit cell parameters. Avec, bvec, and cvec can be either a Vector3D or a number. If it is a number, the x/y/z axis vector is multiplied with the given number and used as the cell axis vector. Flags, if present, is a 3-member array of Integers defining whether the system is periodic along the axis. If convert_coord is true (neither nil nor false), the coordinates of atoms are converted so that the fractional cooordinates remain the same.

In the second form, an isotropic box with cell-length d is set.

In the third form, the existing unit cell is cleared.

This operation is undoable, in any of the above form.

Note: if the sigma values of the cell parameters were already set by Molecule#cell=, those values are left untouched unless the cell itself is cleared.

See Also: Molecule#box, Molecule#cell, Molecule#cell=

calc_angle(n1, n2, n3) → Float

Calculate the bond angle defined by the three atoms. The result is in degree.

See Also: Molecule#calc_angle (Class Method)

calc_bond(n1, n2) → Float

Calculate the bond length between the two atoms.

See Also: Molecule#calc_bond (Class Method)

calc_dihedral(n1, n2, n3, n4) → Float

Calculate the dihedral angle defined by the four atoms. The result is in degree.

See Also: Molecule#calc_dihedral (Class Method)

call_subprocess_async(cmd, end_callback = nil, timer_callback = nil, stdout_file = nil, stderr_file = nil) → Integer

Call subprocess asynchronically. If `end_callback` is given, it will be called (with two arguments self and termination status) when the subprocess terminated. If `timer_callback` is given, it will be called (also with two arguments, self and timer count) periodically during execution of the subprocess. If `timer_callback` returns nil or false, then the subprocess will be interrupted. Returns the process ID as an integer.

The standard output/error stream is directed to the Ruby Console. If stdout_file or stderr_file is given as a filename, the stdout/stderr output will be directed to that file. (If the filename begins with ">>", then the output will be appended to the end of the file; otherwise, the existing file will be replaced.) If it is "/dev/null" or "NUL", then the output will be lost.

See Also: Kernel#call_subprocess

cell → [a, b, c, alpha, beta, gamma [, sig_a, sig_b, sig_c, sig_alpha, sig_beta, sig_gamma]]

Returns the unit cell parameters. If a unit cell is not set, returns nil. Alpha/beta/gamma are in degree. If the sigma value are present, the return value is an array of 12 floats instead of 6.

See Also: Molecule#box, Molecule#box=, Molecule#cell=

self.cell = [a, b, c, alpha, beta, gamma [, sig_a, sig_b, sig_c, sig_alpha, sig_beta, sig_gamma]]
set_cell([a, b, c, alpha, beta, gamma[, sig_a, sig_b, sig_c, sig_alpha, sig_beta, sig_gamma]], convert_coord = nil)

Set the unit cell parameters. Alpha/beta/gamma are in degree. If the right-hand value (or the first argument) is nil, then clear the current unit cell. If the cell parameters are given as an array of 12 floats, then the second half of the array is to represent the sigma value (that are common in crystallographic data). Convert_coord is a flag to specify that the coordinates should be transformed so that the fractional coordinates remain the same. This operation is undoable.

See Also: Molecule#box, Molecule#box=, Molecule#cell

cell_flexibility → bool

Obsolete. Now the unit cell is always flexible (i.e. different frames can have different unit cell)

self.cell_flexibility = bool
set_cell_flexibility(bool)

Obsolete. Now the unit cell is always flexible (i.e. different frames can have different unit cell)

cell_periodicity → [n1, n2, n3] or nil

Get flags denoting whether the cell is periodic along the a/b/c axes. If the cell is not defined, nil is returned.

self.cell_periodicity = [n1, n2, n3] or Integer or nil
set_cell_periodicity([n1, n2, n3] or Integer or nil)

Set whether the cell is periodic along the a/b/c axes. If an integer is given as an argument, its bits 2/1/0 (from the lowest) correspond to the a/b/c axes. Nil is equivalent to [0, 0, 0]. If cell is not defined, exception is raised. This operation is undoable.

cell_transform → Transform

Return the Transform matrix that converts internal coordinates to cartesian coordinates. If the unit cell is not defined, nil is returned.

center_of_mass(group = nil) → Vector3D

Calculate the center of mass for the given set of atoms. If the argument group is null, all atoms are considered.

centralize(group = nil) → self

Translate the molecule so that the center of mass of the given group is located at (0, 0, 0). Equivalent to self.translate(self.center_of_mass(group) * -1). This operation is undoable.

charge(group = nil) → Float

Calculate the total charge (the sum of the "charge" attributes of atoms). If a group is given, only the atoms in the group are considered.

count_bonds(n1, n2) → Integer

Count the (minimum) number of bonds between atoms n1 and n2. If there is no connection between n1 and n2, return -1.

create_atom(name, pos = -1) → AtomRef

Create a new atom with the specified name (may contain residue information) and position (if position is out of range, the atom is appended at the end). The occupancy of the new atom is 1.0, and other attributes are 0 or null. Returns the reference to the atom. This operation is undoable.

See Also: Molecule#add_atom

create_bond(n1, n2, ...) → Integer
create_bonds(n1, n2, ...) → Integer

Create bond(s) between atoms n1 and n2, n3 and n4, and so on. If the atoms already have other bonds, new angles and dihedrals are automatically created. If a bond is already present for a particular pair of atoms, do nothing for that pair. Returns the number of bonds actually created. This operation is undoable.

create_frame(coordinates = nil) → Integer
create_frames(coordinates = nil) → Integer

Same as Molecule#insert_frames(nil, coordinates).

create_graphic(kind, color, points, fill = nil) → Integer

Create a new graphic object. Kind: a symbol representing the kind of the graphic. :line, :poly, :cylinder, :cone, :ellipsoid. Color: an array of 3 (rgb) or 4 (rgba) floating numbers. Points: an array of Vector3Ds or Floats (depending on the graphic type). The arguments points = [p1, p2, ..., pn] and fill have the following meanings for each kind of the graphic.

- line: Points correspond to a set of lines (p1, p2), (p2, p3), ..., (p(n-1), pn). Fill has no meaning.
- poly: Points correspond to a set of connected triangles (p1, p2, p3), (p1, p3, p4), ..., (p1, p(n-1), pn). Fill has no meaning.
- cylinder: p1 = center of the bottom face, p2 = center of the top face, p3 (number) = radius. If fill is true, both faces are drawn. Otherwise, only the side surface is drawn.
- cone: p1 = center of the bottom face, p2 = top point, p3 (number) = radius. If fill is true, the bottom face is drawn. Otherwise, only the side surface is drawn.
- ellipsoid: Two argument types. (1) p1 = center, p2 (number) = radius. (2) p1 = center, p2, p3, p4 = main axis of the ellipsoid (not necessarily orthogonal each other). Fill has no meaning.

Returns the index of the newly created graphic.

See Also: Molecule#remove_graphic

create_pi_anchor(name, group [, type] [, weights] [, index]) → AtomRef

Create a pi anchor, which is a "dummy" atom to represent pi-metal bonds. Name is the name of the new pi anchor, and group is the atoms that define the pi system. Type (a String) is an atom type for MM implementation (default: "##"). Weights is the relative weights of the component atoms; if omitted, then 1.0/n (n is the number of component atoms) is assumed for all atoms. The weight values will be normalized so that the sum of the weights is 1.0. The weight values must be positive. Index is the atom index where the created pi-anchor is inserted in the atoms array; if omitted, the pi-anchor is inserted after the component atom having the largest index.

Pi anchors are appear in the atom list along with other ordinary atoms. The list of component atoms (and their weights) can be retrived by AtomRef#anchor_list.

cubegen(fname, mo, npoints=1000000 [, iflag])
cubegen(fname, mo, origin, dx, dy, dz, nx, ny, nz [, iflag])

Calculate the molecular orbital with number mo and create a cube file. In the first form, the cube size is estimated from the atomic coordinates. In the second form, the cube dimension is explicitly given. Returns fname when successful, nil otherwise. If iflag is non-false, then interrupt check is enabled during calculation.

default_MO_grid(npoints = 80*80*80) → [origin, dx, dy, dz, nx, ny, nz]

Calculate a default MO grid for cube file generation. Origin is Vector3D; dx, dy, dz are Float; nx, ny, nz are Integer. If the molecule does not contain a basis set information, then returns nil.

detachable?(group) → [n1, n2]

Check whether the group is detachable, i.e. the group is bound to the rest of the molecule via only one bond. If it is, then the indices of the atoms belonging to the bond is returned; n1 is the atom belonging to the group, and n2 is the atom not belonging to the group and bound to n1. If the above conditions are not met, nil is returned.

dihedrals → MolEnumerable

Returns a MolEnumerable object representing the array of dihedrals. A dihedral n1-n2-n3-n4 is represented by an array [n1, n2, n3, n4], where n1, n2, n3, n4 are the atom index integers.

See Also: Molecule#ndihedrals

dir → String

Returns the full path name of the directory in which the file associated with the molecule is located. If the molecule has no associated file, then returns nil.

See Also: Molecule#path

display

Refresh the display if this molecule is bound to a view. Otherwise do nothing.

dock(mol, base1, base2, rem1 = nil, rem2 = nil, len = nil, dihed = nil, def1 = nil, def2 = nil)

Combine two molecules. A new bond is created between base1 and base2. Rem1 and rem2 specify the atom (or fragment) to be removed when creating the new bond. If nil is specified for either of them, a dummy atom (which has a name beginning with '#') is looked for, and if none is found then no atom is removed and the new bond is directed so that it is most remote from any of the existing bonds.

Rem1 and rem2 can also be Vector3D objects that specify the direction of the new bond. In this case, no atoms are removed.

If len is specified, then the length of the new bond is set to this value. Otherwise, it is set to 1.5.

If dihed is specified, then the dihedral angle def1-base1-base2-def2 is set to this value (in degree, not radian). If nil is specified for either def1 or def2 (or both), then the atom which is connected to base1 (base2) and has the smallest index is used.

Returns the group of atom indices that have been added. This operation is undoable.

See Also: Molecule#detachable? (for description of detachability), Molecule#dock_formula, Molecule#dock_fragment

dock_formula(str, group = selection)

Create a fragment from str and replace the group with the generated fragment. This method is invoked when a detachable selection is double-clicked and user enters the formula in the dialog box. This operation is undoable.

See Also: Molecule#dock, Molecule#dock_fragment

dock_fragment(fragment, group = selection)

Replace the specified group with the given fragment, which is another Molecule object. This operation is undoable.

See Also: Molecule#dock, Molecule#dock_formula

dump(group = nil) → String

Create a String that represent the atom list. If a group is given, only the atoms in the group will be included.

See Also: Molecule#from_dump

dup → (new) Molecule

Duplicate a molecule. All entries are deep copied, so that modifying the newly created object does not affect the old object in any sense.

duplicate_atom(atomref, pos = -1) → AtomRef

Create a new atom with the same attributes (but no bonding information) with the specified atom. Returns the reference to the new atom. Useful as a convenient version of Molecule#create_atom, with the various atomic attributes duplicated from the reference atom. This operation is undoable.

each_atom(atom_group = nil) {|aref| ...}

Execute the block for each atom, with the AtomRef object as the argument. If an atom group is given, only the specified atoms are processed. Otherwise, equivalent to self.atoms.each, except that the return value is self.

each_fragment {|group| ...}

Execute the block for each fragment in the molecule, with the IntGroup object representing the fragment as the block argument. No new atoms or bonds should be created or removed during the execution of the block, otherwise the results will be unpredictable (may even cause a crash).

each_frame {|n| ...}

Set the frame number from 0 to nframes-1 and execute the block. The block argument is the frame number. After completion, the original frame number is restored. Roughly equivalent to the following code snippet:

    old_frame = self.frame
    for n in 0..self.nframes-1
      self.frame = n
      yield(n)
    end
    self.frame = old_frame

See Also: Molecule#nframes

elpot(idx) → [pos, potential]

Get the electrostatic potential info at the given index. The electrostatic potential are read from the output of quantum chemistry softwares. If present, then the return value is [Vector3D, Float] (position and potential). If not present, then returns nil.

See Also: Molecule#loadlog (to load GAMESS output), Molecule#nelpots

expand_by_symmetry(group, sym, dx=0, dy=0, dz=0, allow_overlap = false) → Array

Expand the specified part of the molecule by the given symmetry operation. Sym is the index to the symmetries array, and dx/dy/dz are the integers representing the translational operations along the unit cell axes. Returns an array of indices of the expanded atoms (corresponding the atoms in group).

If allow_overlap is true, then new atoms are created even when the coordinates coincide with the some other atom (special position) of the same element; otherwise, such atom will not be created and the index of the existing atom is given in the returned array.

This operation is undoable.

extract(group, dummy_flag = nil) → (new) Molecule

Extract the atoms represented by the given group, and return as a new Molecule object. If dummy_flag is true, then the atoms that are not selected but are connected to any selected atoms are also included as dummy atoms. (i.e. with element "Du" and names beginning with an underscore).

find_close_atoms(atom, limit = 1.2, radius = 0.77) → Array of Integers

Find atoms that are within the threshold distance from the given atom. If limit is a positive number, the threshold distance is the sum of the vdw radii times limit. If limit is a negative number, its absolute value is used for the threshold distance in angstrom. If limit is not given, a default value of 1.2 is used.

An array of atom indices is returned. If no atoms are found, an empty array is returned.

The atom argument can also be a Vector3D (or any other object that can be converted to a Vector3D), representing cartesian coordinates. In this case, the van der Waals of the atom can also be specified (the default value = 0.77 represents the van der Waals radius of carbon).

find_conflicts(limit[, group1[, group2[, ignore_exclusion]]]) → [[n1, n2], [n3, n4], ...]

Find pairs of atoms that are within the limit distance. If group1 and group2 are given, the first and second atom in the pair should belong to group1 and group2, respectively. By default, the atom pairs separated by one to three bonds are excluded. However, if ignore_exclusion is given as non-false, then those pairs are also included.

find_dummy_atoms(how_many = nil)

Find dummy atoms, i.e. the atoms whose element is "Du" and whose name begins with an underscore.

fit_coordinates(group, ref, weight = nil) -> [transform, rmsd]

Calculate the transform to fit the given group to the set of reference coordinates. The reference coordinates ref is given as either a frame number, an array of Vector3Ds or arrays, or an LAMatrix. Weight can be optionally given as an array of numbers or an LAMatrix. If weight is not given, the atomic weights are used.

Return values are the transform (that converts the present coordinates to the target coordinates) and root mean square deviation (without weight).

fragment(n1, *exatoms) → IntGroup
fragment(group, *exatoms) → IntGroup

Find the fragment (i.e. a group of connected atoms) including the atom n1 or the atom group. If additional arguments are given, those atoms will not be counted during the search.

frame → Integer

Get the current frame shown in the window.

self.frame = index
select_frame(index)

Select the specified frame. If successful, returns true, otherwise returns false.

See Also: Molecule#nframes

from_dump(str) → self

Read the description of atoms from the String of the dump format. Self must be empty.

See Also: Molecule#dump

get_atom_attr(index, key)

Get the atom attribute for the specified atom. Equivalent to self.atoms[index].key. See the methods of class AtomRef for available atrributes.

get_bond_order(idx) → Float
get_bond_orders(group) → Array

Get the bond order. In the first form, the bond order of the idx-th bond is returned. In the second form, the bond orders at the indices in the group are returned as an array. If no bond order information have been assigned, returns nil (the first form) or an empty array (the second form).

get_coord_from_frame(index, group = nil) → self

Copy the coordinates from the specified frame. If group is specified, then only the atoms in the group are modified. The third argument (`cflag`) is now obsolete; it used to specify whether the cell information should be copied, but now they are always copied. This operation is undoable.

get_view_center → Vector3D

Get the current center point of the view.

See Also: Molecule#set_view_center

get_view_rotation → [[ax, ay, az], angle]

Get the current rotation for the view. Angle is in degree, not radian. The sign of the angle is positive when the rotation and the axis vector follow the left-hand rule (i.e. clockwise when viewed from the tip of the axis). Note that this is opposite from the OpenGL convention.

See Also: Molecule#set_view_rotation

get_view_scale → Float

Get the current scale for the view. Scale is expressed with a dimensionless floating-point number in the range -5.0 to 5.0. The scale parameter is transformed to perspective parameters (fovy and distance) in the following way: for negative scale, fovy = 30 degree and distance = cot(15) * 10^(-scale) * 10 Å; for positive scale, fovy = 30 * 10^(-scale) degree and distance = cot(15) * 10 Å.

See Also: Molecule#set_view_scale

guess_bonds(limit = 1.2) → Integer

Create bonds between atoms that are within the threshold distance. If limit is a positive number, the threshold distance is the sum of the vdw radii times limit. If limit is a negative number, its absolute value is used for the threshold distance in angstrom. If limit is not given, a default value of 1.2 is used. The number of the newly created bonds is returned. This operation is undoable.

hide_graphic(graphic_index) → self

Unset the visibility flag of the graphic_index-th graphic object.

See Also: Molecule#show_graphic

impropers → MolEnumerable

Returns a MolEnumerable object representing the array of impropers. improper is represented by an array of four atom indices.

See Also: Molecule#nimpropers

insert_frame(integer, coordinates = nil) → IntGroup
insert_frames(intGroup = nil, coordinates = nil) → IntGroup

Insert new frames at the indices specified by the intGroup. If the first argument is an integer, a single new frame is inserted at that index. If the first argument is nil, a new frame is inserted at the last. If non-nil coordinates is given, it should be an array of arrays of Vector3Ds, and those coordinates are set to the new frame. Otherwise, the current coordinates are copied to the new frame. Returns an IntGroup representing the inserted frames if successful, nil if not.

inspect → String

Returns a string in the form "Molecule[name]" if the molecule has the associated document. Otherwise, an internal representation like "<Molecule:0x****>" is returned.

invert(center = [0,0,0], group = nil) → self

Invert the molecule with the given center. If group is given, only the atoms in the group are moved. This operation is undoable.

is_atom_visible(index) → bool

Check whether the atom is visible or not. Unlike AtomRef#hidden, this method takes care of the Molecule attributes show_hydrogens, show_expanded and show_dummy_atoms.

line_mode
line_mode(bool)
self.line_mode = bool

Set the flag whether to draw the model in line mode. If no argument is given, the current flag is returned.

loadcom(filename) → bool
loadgjf(filename) → bool

Load a molecule from a Gaussian input file.

loadcrd(filename) → bool

Import the frames from a crd file (from AMBER etc.). The molecule must not be empty, because a crd file does not contain structure information,

loaddat(file) → bool

Read coordinates and ESP information (if present) from a GAMESS dat file. (TODO: read MO info as well) Return true if successful.

loaddcd(file) → bool

Read coordinates from a dcd file. The molecule must not be empty, because a dcd file does not contain structure information. This method is aware of the endian of the input file, so that you do not need to flip the endian when you transfer a dcd file created on other platform. Return true if successful.

loadfchk(file) → bool

Read coordinates and MO information from a Gaussian fchk file. Return true if successful.

loadinp(filename) → bool

Load molecule from a GAMESS input file.

loadlog(filename) → bool

Read coordinates from a GAMESS log file.

loadmbsf(file) → bool

Read a structure from a mbsf (Molby structure format) file. Return true if successful.

loadout(filename) → bool

Read coordinates from a Gaussian output file. If molecule is empty, then structure is built by guessing bonds from the interatomic distances. Otherwise, only the coordinates are read in. Return true if successful.

loadpdb(file) → bool

Read coordinates from a pdb file. If molecule is empty, then structure is build by use of CONECT instructions. Otherwise, only the coordinates are read in. Return true if successful.

loadpsf(file, pdbfile = nil) → bool

Read a structure from a psf file. molecule must be empty. The psf may be an "extended" version, which also contains coordinates. If pdbfile is given, then atomic coordinates are read from that file. Return true if successful.

loadres(file) → bool

Read coordinates from a SHELX input/result file. Return true if successful.

loadtep(file) → bool

Read coordinates from an ORTEP input file. Return true if successful.

loadxyz(file) → bool

Load molecule from a text file describing the cartesian coordinates. The first line may be "natoms a b c alpha beta gamma", which defines crystallographic unit cell; in this case, the coordinates are regarded as crystallographic internal coordinates. (The first "natoms" field is present for historical reasons.)

make_front → nil

Make the window frontmost if this molecule is bound to a view. Otherwise do nothing

max(group = nil) → Vector3D

Return a Vector3D consisting of the largest value of x/y/z coordinates for the atoms in the group. If group is not given, all atoms are considered. Equivalent to self.bounds[1].

max_residue_number(group = nil) → Integer

Returns the maximum residue number used in the given group. If group is not specified, all atoms are considered. If no atom is present, nil is returned.

md_arena → MDArena

Returns the MDArena object associated to this molecule. If no MDArena is associated to this molecule, a new arena is created.

measure_angle(n1, n2, n3) → Float

Calculate the bond angle. The arguments can either be atom indices, the "residue:name" representation, or Vector3D values. The return value is in degree (not radian).

measure_bond(n1, n2) → Float

Calculate the bond length. The arguments can either be atom indices, the "residue:name" representation, or Vector3D values.

measure_dihedral(n1, n2, n3, n4) → Float

Calculate the dihedral angle. The arguments can either be atom indices, the "residue:name" representation, or Vector3D values. The return value is in degree (not radian).

min(group = nil)

Return a Vector3D consisting of the smallest value of x/y/z coordinates for the atoms in the group. If group is not given, all atoms are considered. Equivalent to self.bounds[0].

min_residue_number(group = nil) → Integer

Returns the minimum residue number used in the given group. If group is not specified, all atoms are considered. If no atom is present, nil is returned.

molload(file, *args) → bool

Read a structure from the given file by calling the public method "loadXXX" (XXX is the file type given by the extension). If this method fails, then all defined (public) "loadXXX" methods are invoked, and raises an exception if none of them were successful.

molsave(file, *args) → bool

Write a structure/coordinate to the given file by calling the public method "saveXXX" (XXX is the file type given by the extension).

name → String

Returns the name of the molecule, which is the basename of the filename of the associated document. If the molecule has no associated document, nil is returned.

nangles → Integer

Returns the number of angles.

See Also: Molecule#angles.

natoms → Integer

Returns the number of atoms.

See Also: Molecule#atoms.

nbonds → Integer

Returns the number of bonds.

See Also: Molecule#bonds.

ndihedrals → Integer

Returns the number of dihedrals.

See Also: Molecule#dihedrals.

nelpots → Integer

Get the number of electrostatic potential info.

See Also: Molecule#elpot

neutralize(charge = 0.0, group = nil)

Shift the partial charges of atoms, so that the sum of the charges becomes the specified value. If group is specified, only the atoms in the group are examined.

nframes → Integer

Get the number of frames. Note that the minimum number of frames is 1, not 0.

See Also: Molecule#frame, Molecule#frame=

ngraphics → Integer

Get the number of graphic objects.

nimpropers → Integer

Returns the number of impropers.

See Also: Molecule#impropers.

nresidues → Integer

Returns the number of residues.

See Also: Molecule#residues.

self.nresidues = Integer

Change the number of residues.

See Also: Molecule#residues, Molecule#nresidues.

nsymmetries → Integer

Get the number of currently defined symmetry operations.

See Also: Molecule#symmetries

offset_residue(group, offset) → self

Offset the residue number of the specified atoms. If any of the residue number gets negative, then exception is thrown. This operation is undoable.

orthogonal_vector(v)

Returns an arbitrary unit vector that is orthogonal to v

parameter → Parameter

Get a Parameter object that represents the local parameters for this molecule. This method may call `self.md_arena.prepare(true)` internally, so that the side effect caused by MDArena#prepare may be observed.

path → String

Returns the full path name of the molecule, if it has an associated document. If the molecule has no associated document, then returns nil.

See Also: Molecule#dir, Molecule#name

ps_per_step → Float

Returns the time increment (in picoseconds) for one step (defined by dcd format).

See Also: Molecule#loaddcd, Molecule#ps_per_step=

self.ps_per_step = Float

Set the time increment (in picoseconds) for one step (defined by dcd format).

See Also: Molecule#loaddcd, Molecule#ps_per_step

reflect(axis, center = [0,0,0], group = nil) → self

Reflect the molecule by the plane which is perpendicular to axis and including center. axis must not be a zero vector. If group is given, only the atoms in the group are moved. This operation is undoable.

register_undo(script, *args)

Register an undo operation with the current molecule. When "undo" menu command is selected, a command "script(*args)" is executed. If self has no associated document, do nothing.

remove(group) → self

The atoms in the group are removed from the molecule. This operation is undoable.

remove_angle(n1, n2, n3) → self

Remove angle n1-n2-n3. Returns self. Usually, angles are automatically removed when any of the constituent bonds are removed, so it is rarely necessary to use this method explicitly. This operation is undoable.

See Also: Molecule#remove_bond

remove_bond(n1, n2, ...) → Integer
remove_bonds(n1, n2, ...) → Integer

Remove bond(s) between atoms n1 and n2, n3 and n4, and so on. The angles, dihedrals, and impropers including the removed bonds are automatically removed. If a bond for a particular pair of atoms is not present, do nothing for that pair. Returns the number of bonds actually removed. This operation is undoable.

remove_dihedral(n1, n2, n3, n4) → self

Remove dihedral n1-n2-n3-n4. Returns self. Usually, dihedrals are automatically removed when any of the constituent bonds are removed, so it is rarely necessary to use this method explicitly. This operation is undoable.

See Also: Molecule#remove_bond

remove_frame(intGroup, want_coordinates = false)
remove_frames(intGroup, want_coordinates = false)

Remove the frames at group. If want_coordinates is false (default), returns true if successful and nil otherwise. If want_coordinates is true, an array of arrays of the coordinates in the removed frames is returned.

If the given group corrensponds to all frames, then the current frame is retained. Otherwise, if the current frame is included in the given group, the frame immediately before the group is selected (if no frame is present before the group, the frame with the lowest index is selected).

remove_graphic(index) → index

Remove a graphic object.

See Also: Molecule#create_graphic

remove_improper(n1, n2, n3, n4) → self

Remove improper n1-n2-n3-n4. Returns self. Usually, impropers are automatically removed when any of the constituent bonds are removed, so it is rarely necessary to use this method explicitly. This operation is undoable.

See Also: Molecule#remove_bond

remove_symmetry(count = nil) → Integer
remove_symmetries(count = nil) → Integer

Remove the specified number of symmetry operations. The last added ones are removed first. If count is nil, then all symmetry operations are removed. Returns the number of leftover symmetry operations. This operation is undoable.

renumber_atoms(array) → IntGroup

Change the order of atoms so that the atoms specified in the array argument appear in this order from the top of the molecule. The atoms that are not included in array are placed after these atoms, and these atoms are returned as an intGroup. This operation is undoable.

residues → MolEnumerable

Returns a MolEnumerable object representing the array of residue names.

See Also: Molecule#nresidues

resize_to_fit → self

Resize the model drawing to fit in the window.

rotate(axis, angle, center = [0,0,0], group = nil) → self

Rotate the molecule. The axis must not a zero vector. angle is given in degree (not radian). If group is given, only the atoms in the group are moved. This operation is undoable.

rotate_fragment(n1, n2, angle)

Rotate the molecular fragment. The fragment given by "fragment(n2, n1)" is rotated, with the atom n1 as the center and the vector n2->n1 as the axis. Note the order of the arguments; the fragment including n2 is rotated. This operation is undoable.

rotate_with_axis(x, y, c = nil, group = nil)

Move the molecule (or the group if specified) so that c becomes the origin, x points to the x-axis, and y lies in the xy-plane (with the y-coordinate to be positive). X, y, and c can be either a Vector3D, an atom index, or an atom description like "1:CA1". If c is nil, it is equivalent to [0, 0, 0]. This operation is undoable.

savecom(file) → bool
savegjf(file) → bool

Write a Gaussian input file. Returns true if successful.

savecrd(file) → bool

Write coordinates to a crd file. Returns true if successful.

savedcd(file) → bool

Write coordinates to a dcd file. Returns true if successful.

saveinp(file) → bool

Write a GAMESS input file. Returns true if successful.

savembsf(file) → bool

Write structure as a mbsf file. Returns true if successful.

savepdb(file) → bool

Write coordinates to a pdb file. Returns true if successful.

savepsf(file) → bool

Write structure as a psf file. Returns true if successful.

Note: when a document is saved as a psf file from a menu command, a pdb file is created at the same time. However, this is not the case with the script command savepsf. You need to invoke savepdb explicitly, if you want a pdb file.

savetep(file) → bool

Write an ORTEP input file. Returns true if successful.

search_equivalent_atoms(ig = nil) → Array of Integer

Search topologically equivalent atoms (within the atom group if given). Returns an array of integers of size natoms, each entry designates the equivalent atom with the lowest index, or -1 if no equivalent atoms are present.

selectedMO → IntGroup

Returns a group of selected MO in the "MO Info" table. If the MO info table is not selected, returns nil. If the MO info table is selected but no MOs are selected, returns an empty IntGroup. The numbers in the table are 1-based.

selection → IntGroup

Returns the current selection.

self.selection = group

Set the current selection. The right-hand operand (of class IntGroup) may be nil, in which case all atoms will be unselected. This operation is not undoable. If you need undo, use set_undoable_selection instead.

set_atom_attr(index, key, value)

Set the atom attribute for the specified atom. Equivalent to self.atoms[index].key = value. See the methods of class AtomRef for available atrributes. This operation is undoable.

set_background_color(red, green, blue) → self

Set the background color of the model view. Red, green, blue are in the range of [0, 1].

set_dihedral(n1, n2, n3, n4, angle)

Set the dihedral angle n1-n2-n3-n4 to the specified value. The bond n2-n3 should be rotatable. The fragment including n3 and n4 are rotated. This operation is undoable.

set_graphic_color(graphic_index, new_vaue) → new_value

Change the color of graphic_index-th graphic object. The new value must be an array-like object containing three or four numbers.

set_graphic_point(graphic_index, point_index, new_value) → new_value

Change the point_index-th control point of graphic_index-th graphic object. If the object is a line strip, nil is allowed for the new value, which means the line strip ends at the last point.

set_name(name) → self

Set the name of an untitled molecule. This method requires that the molecule is associated with a window and does not have an associated file yet. Otherwise, an exception is thrown.

set_parameter_attr(type, index, key, value, src) → value

Set the name of an untitled molecule. This method requires that the molecule is associated with a window and does not have an associated file yet. Otherwise, an exception is thrown.

set_undoable_selection(group)

Set the current selection with undo registration. The right-hand operand (of class IntGroup) may be nil, in which case all atoms are unselected. This operation is undoable.

set_view_center(vec) → self

Set the current center point of the view.

See Also: Molecule#get_view_center

set_view_rotation(axis, angle) → self

Set the current rotation for the view. Axis is a Vector3D or an object that can be transformed to a Vector3D. Angle is in degree, not radian. The sign of the angle is positive when the rotation and the axis vector follow the left-hand rule (i.e. clockwise when viewed from the tip of the axis). Note that this is opposite from the OpenGL convention.

See Also: Molecule#get_view_rotation

set_view_scale(scale) → self

Set the current scale for the view. For detailed description of the scale parameter, see Molecule#get_view_scale.

See Also: Molecule#get_view_scale

show_dummy_atoms → bool
show_dummy_atoms(bool)
self.show_dummy_atoms = bool

Set the flag whether to show the dummy atoms. If no argument is given, the current flag is returned.

show_ellipsoids → bool
show_ellipsoids(bool)
self.show_ellipsoids = bool

Set the flag whether to show the thermal ellipsoids. If no argument is given, the current flag is returned.

show_expanded → bool
show_expanded(bool)
self.show_expanded = bool

Set the flag whether to show the expanded atoms. If no argument is given, the current flag is returned.

show_graphic(graphic_index) → self

Set the visibility flag of the graphic_index-th graphic object.

See Also: Molecule#hide_graphic

show_graphite → Integer
self.show_graphite = Integer

Set whether to show the graphite plane. The plane is assumed to be on the xy plane. If the argument is positive, it also indicates the number of rings to display for each direction. If the argument is zero, the plane is not displayed. If no argument is given, the current value is returned.

show_hydrogens → bool
show_hydrogens(bool)
self.show_hydrogens = bool

Set the flag whether to show the hydrogen atoms. If no argument is given, the current flag is returned.

show_periodic_image → [amin, amax, bmin, bmax, cmin, cmax]

Get the number of periodic images to show along each cell axis.

self.show_periodic_image = [amin, amax, bmin, bmax, cmin, cmax]
self.show_periodic_image = bool

Set the number of periodic images to show along each cell axis. If the unit cell is not defined, the values are set but no visual effects are observed. If the argument is boolean, then the show/hide flag is modifed.

show_text(string)

Show the string in the info text box in the molecule window.

show_unitcell → bool
show_unitcell(bool)
self.show_unitcell = bool

Set the flag whether to show the unit cell. If no argument is given, the current flag is returned.

solvate(sbox, size = [10.0, 10.0, 10.0], limit = 3.0) → IntGroup

Solvate the molecule with the given solvent box. The first argument (sbox) must be a Molecule containing the solvent, which must have a unit cell information. The second argument defines the size of the solvated system. A positive number represents an offset to the bounding box of the solute, and a negative number represents an absolute size. The third argument represents the limit distance to avoid conflict between the solute and solvent. The solvent molecule containing atoms within this limit from the solute is removed.

The return value is the IntGroup representing the added solvent atoms. This operation is undoable.

start_step → Integer

Returns the start step (defined by dcd format).

self.start_step = Integer

Set the start step (defined by dcd format).

steps_per_frame → Integer

Returns the number of steps between frames (defined by dcd format).

self.steps_per_frame = Integer

Set the number of steps between frames (defined by dcd format).

symmetry → Array of Transform
symmetries → Array of Transform

Get the currently defined symmetry operations. If no symmetry operation is defined, returns an empty array.

symop_for_transform(transform, is_cartesian = nil) → [sym, dx, dy, dz]

Get the symmetry operation corresponding to the given transform. If is_cartesian is true, the given transform is for cartesian coordinates. Otherwise, the given transform is for fractional coordinates. Raises exception when no cell or no transform are defined. Returns nil if the given transform cannot be expressed as a symmetry operation.

See Also:Molecule#transform_for_symop

transform(transform, group = nil) → self

Transform the molecule by the given Transform object. If group is given, only the atoms in the group are moved. This operation is undoable.

transform_for_symop(symop, is_cartesian = nil) → Transform

Get the transform corresponding to the symmetry operation. The symop can either be an integer (index of symmetry operation) or [sym, dx, dy, dz]. If is_cartesian is true, the returned transform is for cartesian coordinates. Otherwise, the returned transform is for fractional coordinates. Raises exception when no cell or no transform are defined.

See Also:Molecule#symop_for_transform

translate(vec, group = nil) → self

Translate the molecule by vec. If group is given, only the atoms in the group are moved. This operation is undoable.

self.undo_enabled = bool

Enable or disable undo.

undo_enabled? → bool

Returns true if undo is enabled for this molecule; otherwise no.

self.update_enabled = bool

Enable or disable screen update. This is effective for automatic update on modification. Explicit call to Molecule#display always updates the screen.

update_enabled? → bool

Returns true if screen update is enabled; otherwise no.

wrap_unit_cell(group) → Vector3D

Move the specified group so that the center of mass of the group is within the unit cell. The offset vector is returned. If no unit cell is defined, exception is raised. This operation is undoable.