Editors¶

Edit Modes¶

Editors support two modes: An unbuffered edit mode and a buffered edit mode. In the unbuffered edit mode, dependent information such as the spatial organizer and the internal coordinate system (in case of the XCSEditor) are updated after every change. In buffered edit mode, the updates are delayed until one of the following happens:

• The last editor goes out of scope.
• XCSEditor.UpdateICS() or ICSEditor.UpdateXCS() is called explicitly.

The editors follow the RIAA (resource allocation is initialisation) principle: Whenever an editor is requested an internal reference counter is incremented. In the destructor, this reference count is decremented. When the count drops to zero, the dependent infomation is updated.

In Python, one can not rely on the destructors being called. It is adviced to always put a call to XCSEditor.UpdateICS() or ICSEditor.UpdateXCS() when the editing is finished. Alternatively, starting from Python version 2.6, one can use the with statement to make sure the destructor are called and the dependent information is updated.

Basic Editing Operations¶

The basic functionality of editors is implemented in the EditorBase class.

class ost.mol.EditorBase¶

Inherited by XCSEditor, ICSEditor.

InsertChain(chain_name)¶

Add new chain to the entity

Parameters:	chain_name (string) – The chain’s name. In the scope of an entity, chain names are unique. If a chain of the same already exists an IntegrityError is raised.
Returns:	ChainHandle

AppendResidue(chain, residue_name[, res_num])¶

Append residue to the end of the chain. If res_num is not given, the residue number will be set to the residue number of the last added residue plus one. The insertion code is the same.

Parameters:	chain (ChainHandle) – Must be a valid chain residue_name (string) – 3-letter-code of the residue, e.g. GLY.
Returns:	ResidueHandle

InsertAtom(residue, atom_name, pos, element="", occupancy=1.0, b_factor=0.0, is_hetatm=False)¶

Insert new atom and add it to residue. For atoms with alternative atom locations use InsertAltAtom(). If the element parameter is a valid element, the atom properties mass, charge, and radius are set to default values for that element. If element is an empty string (or an invalid element), the properties are set to rather meaningless default values. You may later set any of the properties manually.

Parameters:

residue (ResidueHandle) – is the parent residue and must be valid atom_name (string) – is the atom name. While free to choose a name, it is adviced to properly name the atoms according to IUPAC rules as several algorithms as well as most builders in the conop module rely on proper naming. pos (geom.Vec3) – is the position of the atom in global coordinates element (class:string) – is the atom’s element. If set to a a valid element, atom properties such as mass, charge, radius are set based on default values for that element. If the element string is empty, or unknown, the properties are filled with rather meaningless default values. occupancy (float) – The occupancy of the atom. between 0 and 1 b_factor (float) – temperature factor. is_hetatm (bool) – whether the atom is an atom coming from a HETATM record.

Returns:

AtomHandle

Editor for the External Coordinate System¶

The XCSEditor defines the interface for manipulating the external coordinate system. The external coordinate system directly operates on atom positions in euclidian space.

class ost.mol.XCSEditor¶

Inherits EditorBase

ApplyTransform(transform)¶

Apply a transformation to the entity. The transformation is applied to all atoms positions.

Parameters:	transform (geom.Mat4) – The transformation to be applied

SetTransform(transform)¶

Set the entity transformation. See also ApplyTransform()

Parameters:	transform (geom.Mat4) – The transformation to be applied

SetAtomPos(atom, pos)¶

Set the (transformed) position of atom. This method will also update the original position of the atom by applying the inverse of the entity transform.

Parameters:	atom (ost.mol.AtomHandle) – must be a valid atom handle pos (geom.Vec3) – The new position

SetOriginalAtomPos(atom, pos)¶

Set the origininal (untransformed) position of the atom. This method will also update the transformed position by applying the entity transform to the original pos.

Parameters:	atom (ost.mol.AtomHandle) – must be a valid atom handle pos (geom.Vec3) – The new untransformed position

Editor for the Internal Coordinate System¶

The ICSEditor is used to manipulate the internal coordinate system that is defined by bond lengths and angles. You can create an editor with the EditICS method of the EntityHandle.

The use XCSEditor and ICSEditor are mutually exclusive. This means that whenever a XCSEditor has pending changes, the results of using an ICSEditor is undefined and vice versa.

class ost.mol.ICSEditor¶

Inherits EditorBase

SetTorsionAngle(torsion, angle)¶

Set the angle of the given torsion. If the edit mode of the editor is set to buffered, the external coordinates remain unchanged. If set to unbuffered, the external coordinates are immediately recalculated.

See :	UpdateICS()
Parameters:	torsion (TorsionHandle) – A valid torsion angle (float) – The angle in radians
Raises :	RuntimeError when the torsion handle is invalid

UpdateXCS()¶

Apply all remaining changes to the internal coordinate system and recalculate external coordinates. In unbuffered edit mode, calling this method has no effect.

SetBondLength(bond, length)¶

Sets the length of a bond. If the edit mode of the editor is set to buffered, the external coordinates remain unchanged. If set to unbuffered, the external coordinates are immediately recalculated.

See :	UpdateICS()
Parameters:	bond (BondHandle) – A valid bond handle length (float) – The bond length in Angstroem.
Raises :	RuntimeError when the bond handle is invalid

SetAngle(atom1, atom2, atom3, angle)¶

Sets the angle between 3 atoms. The first atom must be connected to the second, the second to the third with a bond. If the edit mode of the editor is set to buffered, the external coordinates remain unchanged. If set to unbuffered, the external coordinates are immediately recalculated.

See :	UpdateICS()
Parameters:	atom1 (AtomHandle) – The first atom. Must be valid atom2 (AtomHandle) – The second atom. Must be valid atom3 (AtomHandle) – The third atom. Must be valid angle – The angle in radians
Raises :	RuntimeError when one of the atoms is invalid or there is no bond between atom1 and atom2 or atom2 and atom3.