Skip to content
Snippets Groups Projects
Select Git revision
  • develop protected
  • master default protected
  • ubuntu_ci
  • mmtf
  • non-orthogonal-maps
  • no_boost_filesystem
  • data_viewer
  • 2.9.3
  • 2.9.2
  • 2.9.1
  • 2.9.0
  • 2.8.0
  • 2.7.0
  • 2.6.1
  • 2.6.0
  • 2.6.0-rc4
  • 2.6.0-rc3
  • 2.6.0-rc2
  • 2.6.0-rc
  • 2.5.0
  • 2.5.0-rc2
  • 2.5.0-rc
  • 2.4.0
  • 2.4.0-rc2
  • 2.4.0-rc
  • 2.3.1
  • 2.3.1-rc
27 results
Blame Permalink
editors.rst 24.22 KiB

Editors

The structure, topology and connectivity of :class:`entities <EntityHandle>` is edited via editors. This includes operations such as changing atom positions, connecting atoms with bonds as well as adding and removing chains, residues and atoms. There are two flavors of editors, one for the internal coordinate system (:class:`ICSEditor`) and one for the external coordinate system (:class:`XCSEditor`).

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.
  • :meth:`XCSEditor.UpdateICS` or :meth:`ICSEditor.UpdateXCS` is called explicitly.

The editors follow the RIAA (resource allocation is initialization) 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 information is updated.

In Python, one can not rely on the destructors being called. It is advised to always put a call to :meth:`XCSEditor.UpdateICS` or :meth:`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.

Note

To use the editing functions available in :class:`EditorBase`, it is recommended to use the external coordinate system :class:`XCSEditor` for performance reasons.

Inherited by :class:`XCSEditor`, :class:`ICSEditor`.

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.

Inherits :class:`EditorBase`

Editor for the Internal Coordinate System

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

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

Note

For speed reasons, the internal coordinate system is not initialised until the first call to :meth:`EntityHandle.EditICS`. This involves the build-up of a directed-graph for the bond network as well as calculating the internal coordinate matrices.

Warning

The :class:`ICSEditor` has a very significant performance impact on the structure, and can make subsequent access or modifications on the entity extremely slow to keep the internal coordinate system up-to-date. The :class:`ICSEditor` is never used in SWISS-MODEL, ProMod3 or CAMEO. Only open one if you absolutely need to.

Inherits :class:`EditorBase`