The structure, topology and connectivity of entities 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.

Editor for 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. A specific atom position can be changed with XCSEditor::SetAtomPos. XCSEditor::ApplyTransform applies a transformation to all atoms.

Editor for internal coordinate system

The ICSEditor is used to manipulate the internal coordinate system that is defined by bond lengths and angles. By default the internal coordinate system is not calculates. However, upon requesting an ICSEditor for the first time, the internal coordinate system is initialized. This involves the build-up of a directed-graph for the bond network as well as calculating the internal coordinate matrices.

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

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, startin from Python version 2.6, one can use the with statement to make sure the destructor are called and the dependent information is updated.