Class: AtomRef
Parent: Object

Description

Overview

The class AtomRef points to an atom at a particular index in a Molecule. AtomRef does not implement initialize nor new methods; i.e. an AtomRef object cannot be created explicitly by calling a constructor method. Instead, an AtomRef object is implicitly created as a return value from such methods like Molecule#add_atom, Molecule#create_atom, Molecule#duplicate_atom and MolEnumerable#[], or given as a block argument in some iterator methods such as Molecule#each_atom and MolEnumerable#each.

Atom Attributes

An atom has many attributes, such as name, position, atom type, and so on. All atom attributes have the corresponding accessor (setter/getter) methods. Some attributes are read only, in which case the setter functions cause exception.

AtomRef and Editing Molecule

An AtomRef object contains the parent Molecule and the index (non-negative integer). The index is not automatically updated when the parent Molecule is edited; in such case, the AtomRef object may point to a different atom, or even cause out-of-range exception. 

% m = Molecule.from_formula("CH4")
-->#<Molecule:0x16400bf8>
% m.dump
   0 RES.1   C1   ""   C    0.000   0.000   0.000  0.000 [1,2,3,4]
   1 RES.1   H1   ""   H   -0.355   0.000  -1.020  0.000 [0]
   2 RES.1   H2   ""   H   -0.355  -0.883   0.510  0.000 [0]
   3 RES.1   H3   ""   H   -0.355   0.883   0.510  0.000 [0]
   4 RES.1   H4   ""   H    1.080   0.000   0.000  0.000 [0]
-->
% a = m.atoms[3]  #  Points to "H3"
-->#<AtomRef:0x164449e8>
% a.name
-->"H3"
% m.remove([0])   #  Remove atom 0: now "a" points to "H4"
-->
% a.name
-->"H4"
% m.remove([0])   #  Remove atom 0 again: "a" becomes out of range
-->
% a.name
("atom index out of range" exception)

Public Instance methods

anchor_list → [n1, w1, n2, w2, ...]
self.anchor_list = [n1, w1, n2, w2, ...]

Get/set the list of component atoms for a pi-anchor. N1, n2, ... are the component atom indices from which the pi anchor is defined, and w1, w2, ... are the significance of each component atom.

aniso → [f11, f22, f33, f12, f13, f23]
self.aniso = [f11, f22, f33, f12, f13, f23]
self.aniso = [f11, f22, f33, f12, f13, f23, type]

Get/set the anisotropic thermal factors. If no anisotropic thermal factors are defined for this atom, the getter returns nil. The setter can accept nil as the right-hand value, which clears anisotropic thermal factors for this atom.

The anisotropic thermal parameters are defined as in ORTEP type 0, with the following formula:

   exp(-(f11*h2 + f22*k2 + f33*l2 + 2*f12*h*k + 2*f13*h*l + 2*f23*k*l))

If the extra "type" value is given as in the third form, other types of thermal parameters can be specified. The type value corresponds to that of the ORTEP specification.

For type = 0, 1, 2, 3, and 10:
   pow(B, -D*(f11*h2 + f22*k2 + f33*l2 + C*f12*h*k + C*f13*h*l + C*f23*k*l))

  • type = 0: B = e, C = 2, D = 1 (default)
  • type = 1: B = e, C = 1, D = 1
  • type = 2: B = 2, C = 2, D = 1
  • type = 3: B = 2, C = 1, D = 1
  • type = 10: B = e, C = 2, D = 2*pi2

For type = 4, 5, 8, and 9:
   exp[-D*(a12*f11*h2 + a22*f22*k2 + a32*f33*l2 + C*a1*a2*f12*h*k + C*a2*a3*f23*k*l + C*a1*a3*f13*h*l)]

  • type = 4: C = 2, D = 1/4
  • type = 5: C = 1, D = 1/4
  • type = 8: C = 2, D = 2*pi2
  • type = 9: C = 1, D = 2*pi2

The thermal parameters are described in crystallographic coordinates, so that they are only meaningful when a crystallographic unit cell is defined (see also: Molecule#cell, Molecule#cell=). Nevertheless, setting anisotropic parameters without defining a unit cell does not cause exception, in which case a trivial unit cell ([1, 0, 0], [0, 1, 0], [0, 0, 1]) is implicitly assumed.

atom_type → String
self.atom_type = String

Get/set the atom type for molecular mechanics calculations. The atom type is a string consisting of up to 4 printable ASCII characters (case sensitive), with an optional "variant" part consisting of a period followed by one case-insensitive alphanumeric character. Thus, the following strings are all valid atom types: "ca", "C*", "Zn" ("zn" or "ZN" are different atom types), "CAHN.1".

The atom type with a variant part behaves similarly as the same atom type without the variant, except when a parameter is explicitly defined for the variant-containing atom type. For example, suppose there is an atom with type "cp.1" bound to an atom with type "ca"; when a bond parameter "ca-cp.1" is defined, this parameter is used for this bond; otherwise, a bond parameter "ca-cp" is looked for, and if one is found it is used for this bond.

The atom type "X" and "x" are reserved as wildcards. When parameters are looked for, these atom types match any atom types. Note that these are only wildcard atom types defined in Molby; atom types such as "C*" or "C?" are just individual atom types, with no "matching" behavior.

atomic_number → Integer
self.atomic_number = Integer

Get/set the atomic number. Setting an atomic number also causes change of the element and weight attributes.

See Also: AtomRef#element, AtomRef#weight.

charge → Float
self.charge = Float

Get/set the partial charge. The partial charge is a value used in molecular mechanics calculations for evaluation of electrostatic interactions, and is different from an integer charge as defined in PDB format. For the latter attribute, use AtomRef#int_charge and AtomRef#int_charge= methods.

connects → Array of Integers

Get the connection table. A connection table is a list of atoms that are connected to this atom, represented by an array of atom indices (0-based). This is a read-only attribute; if new bonds are to be created or removed, Molecule#create_bond or Molecule#remove_bond should be used.

element → String
self.element = String

Get/set the chemical element. The chemical element is represented by a two-character string, the first uppercase character and the second (optional) lowercase character, although the right-hand argument for the setter is case-insensitive. It follows that the three-character element symbols for newly discovered elements cannot be used; they are hardly useful for molecular modeling anyway.

Setting the chemical element also causes change of the atomic_number and weight attributes.

See Also: AtomRef#atomic_number, AtomRef#weight.

exclusion → [[i1, i2, ...], [j1, j2, ...], [k1, k2, ...]]

Get the exclusion table, which is used to "exclude" the pair of atoms from the calculation of the non-bonding interaction. [i1, i2, ...] are the atoms which are directly connected to this atom (1-2 exclusion). [j1, j2, ...] are the atoms (other than self) that are connected to [i1, i2, ...] and not in the 1-2 exclusion list (1-3 exclusion). [k1, k2, ...] are the atoms (other than self) that are connected to [j1, j2, ...] and not in the 1-2 nor 1-3 exclusion list.

This is a read-only attribute.

This method requires that the MDArena object for the parent molecule is already established and prepare'd.

f → Vector3D
self.f = Vector3D

Get the force value from the last MM/MD calculation. The value is in internal force unit, amu Å fs-2 (amu is the atomic mass unit, fs is femtosecond). The setter method is also implemented, however it is seldom useful.

fix_force → Float
self.fix_force = Float

Get/set the force constant to fix the atom at the particular position during MM/MD calculations. The value is in kcal/mol. If the force constant is positive, an auxiliary harmonic potential is applied for this atom. If the force constant is negative, the forces are calculated as usual but the velocity of the atom is set to zero in every step. The latter is physically problematic, so use of negative force is not recommended.

See Also: AtomRef#fix_pos

fix_pos → Vector3D
self.fix_pos = Vector3D

Get/set the position to fix the atom during MM/MD calculations. The fix_force should also be set.

See Also: AtomRef#fix_force

fract_r → Vector3D
self.fract_r = Vector3D

Get/set the fractional coordinates as a Vector3D. If the crystallographic unit cell is not defined, these methods are equivalent to AtomRef#r and AtomRef#r=, respectively.

fract_x → Float
self.fract_x = Float

Get/set the fractional coordinate x. If the crystallographic unit cell is not defined, these methods are equivalent to AtomRef#x and AtomRef#x=, respectively.

fract_y → Float
self.fract_y = Float

Get/set the fractional coordinate y. If the crystallographic unit cell is not defined, these methods are equivalent to AtomRef#y and AtomRef#y=, respectively.

fract_z → Float
self.fract_z = Float

Get/set the fractional coordinate z. If the crystallographic unit cell is not defined, these methods are equivalent to AtomRef#z and AtomRef#z=, respectively.

hidden → Boolean
self.hidden = Boolean

Get/set the hidden flag. This is an atom attribute, and is independent with the Molecule attribute such as Molecule#show_hydrogens, Molecule#show_dummy_atoms and Molecule#show_expanded. If you want to examine the visibility of an atom by taking these attributes into consideration, try Molecule#is_atom_visible.

index → Integer

Get the atom index as an integer. This is a read-only attribute; if you want to change the order of the atoms, you should use Molecule#renumber_atoms.

int_charge → Integer
self.int_charge = Integer

Get/set the integer charge. This is the integer charge of the atom as defined in PDB format, and different from the partial (fractional) charge used in MM/MD calculations. For the latter attribute, use AtomRef#charge and AtomRef#charge= methods.

mm_exclude → Integer
self.mm_exclude = Integer

Get/set the flag whether to exclude this atom from MM/MD calculation. The atom is to be excluded if the flag is non-zero.

molecule → Molecule

Get the parent molecule object.

name → String
self.name = String

Get/set the atom name. An atom name consists of up to 4 printable ASCII characters.

occupancy → Float
self.occupancy = Float

Get/set the occupancy.

periodic_exclude → Integer
self.periodic_exclude = Integer

Get/set the flag whether to exclude this atom from periodic calculation. The atom is to be excluded if the flag is non-zero.

r → Vector3D
self.r = Vector3D

Get/set the atom position as a Vector3D. The atom positions are always in cartesian coordinates, even when the crystallographic unit cell is defined. To handle crystallographic fractional coordinates, use AtomRef#fract_r and AtomRef#fract_r=.

res_name → String

Get the residue name. A residue name consists of up to 4 printable ASCII characters. This is a read-only attribute; if a residue name is to be changed, use Molecule#assign_residue.

res_seq → Integer

Get the residue number. Residue numbers are 1-based, and the number 0 means "no residue assigned". This is a read-only attribute; if a residue number is to be changed, use Molecule#assign_residue.

seg_name → String
self.seg_name = String

Get/set the segment name. A segment name consists of up to 4 printable ASCII characters.

seg_seq → Integer
self.seg_seq = Integer

Get/set the segment number.

sigma → Vector3D
sigma_x → Float
sigma_y → Float
sigma_z → Float
self.sigma = Vector3D
self.sigma_x = Float
self.sigma_y = Float
self.sigma_z = Float

Get/set the "sigma" (standard deviation) for the fractional coordinates. Usually these values are read from crystallographic data.

symop → nil or [sym, dx, dy, dz, base]
self.symop = [sym, dx, dy, dz, base]
self.symop = nil

Get/set the symmetry operation. If this atom is not symmetry expanded, then nil is returned. Otherwise, an array of symmetry operation index, cell translation (x, y, z), and the original atom index. When this attribute is set, you will be responsible for keeping the other attribute consistent (for example, the atomic number and atom types should be the same with the base atom). If the right-hand argument has less than five elements or some of the elements are nil, then that attribute is not changed.

See Also: Molecule#expand_by_symmetry

temp_factor → Float
self.temp_factor = Float

Get/set the (isotropic) temperature factor. For anisotropic temperature factors, see AtomRef#aniso.

uff_type → String
self.uff_type = String

Get/set the UFF atom type as a 5-character string.

v → Vector3D
self.v = Vector3D

Get/set the velocity value from the last MM/MD calculation. The value is in Å fs-1 (fs is femtosecond).

weight → Float
self.weight = Float

Get/set the atomic weight. This attribute is automatically updated when atomic_number or element is modified, whereas changing the weight attribute does not cause automatic update of either atomic_number or element attribute.

x → Float
self.x = Float

Get/set the cartesian coordinate x. To handle crystallographic fractional coordinates, use AtomRef#fract_x and AtomRef#fract_x=.

y → Float
self.y = Float

Get/set the cartesian coordinate y. To handle crystallographic fractional coordinates, use AtomRef#fract_y and AtomRef#fract_y=.

z → Float
self.z = Float

Get/set the cartesian coordinate z. To handle crystallographic fractional coordinates, use AtomRef#fract_z and AtomRef#fract_z=.